换来了什么

• 部署极简:out/ 目录整个拷上服务器/OSS 就完事,不需要 PM2、 不需要容器、不需要考虑 Node 版本漂移;
• 天然抗流量:静态文件随便被 CDN 缓存,官网场景下几乎不存在 「被打挂」的概念;
• 安全面小:没有服务端运行时,攻击面收缩到静态文件本身;
• 构建期报错:所有数据获取都发生在 next build,内容错了构建直接 失败,坏内容到不了线上。

失去了什么

静态导出本质是把所有「动态」挪到构建期或客户端,以下能力直接不可用:

对品牌官网和技术博客,这个清单几乎无痛:内容发布频率低(重新构建即 「ISR」),交互都在客户端,表单可以走第三方代收再通知到企微/邮件。

常用的「伪装动态」手法

1. Route Handler + force-static 生成派生文件。 RSS、sitemap 这类「构建期可确定」的动态产物:

// app/rss.xml/route.ts
export const dynamic = "force-static";

export async function GET() {
  return new Response(buildRss(), {
    headers: { "Content-Type": "application/rss+xml; charset=utf-8" },
  });
}

构建时执行一次,输出落成真正的 out/rss.xml 静态文件。

2. generateStaticParams 展开所有路径。 /posts/[slug] 这类动态路由必须在构建期穷举:

export function generateStaticParams() {
  return getAllPosts().map((post) => ({ slug: post.slug }));
}

忘了写这个函数,动态路由在静态导出下会被静默跳过——不报错,只是 产物里没有那些页面,发布后才发现 404。

3. 数据获取全部收口到构建期模块。 文件读进内存、校验、缓存,页面组件只消费纯函数结果。好处是测试 不需要起 Next,数据层单测就是普通 Node 测试。

判断 checklist

什么项目适合静态导出:

• 内容发布频率低,发新内容 = 触发一次重新构建可以接受;
• 没有按请求变化的个性化内容(登录态、A/B、地理定向);
• 搜索/评论/表单这类动态能力愿意交给第三方或客户端方案;
• 有 CI 能自动构建发布(没有的话,发布 = 手动跑命令)。

反过来,只要有任何一条硬性不满足——比如需要 SSR 做 SEO 的个性化 首页——就老实用 next start 或托管到 Vercel,别跟 output: 'export' 较劲,它的边界是设计如此,不是 bug。

一句话结论

静态导出适合「内容即产品」的站:官网、博客、文档站。它把复杂度从 运行时挪到了构建期,而构建期复杂度是靠 CI 和纪律管理的,比运行时 复杂度便宜得多。

目录结构

website/
├── packages/
│   ├── www.yunjuiot.com.cn/   # 公司主站(端口 3000)
│   ├── www.elinchong.com/     # 品牌站(端口 3001)
│   ├── www.xunhong168.com/    # 单页官网(端口 3002)
│   └── www.shenyifei.com/     # 这个博客(端口 3003)
├── shared/                    # 跨包共享资产(pcb3d 流水线等)
├── scripts/                   # OG 封面、PDF 等 Python 生成脚本
└── docs/plans/                # 每个功能的设计文档

每个站点是一个独立的 Next.js App Router 包,有自己的 package.json 和 next.config.ts,互不引用对方的组件。共享的只有根目录的依赖声明、 生成脚本和资产——组件级别的「复用」我刻意没做,后面说为什么。

依赖:全在根上

站点级 package.json 只声明 scripts,依赖全部挂在仓库根:

{
  "name": "www.shenyifei.com",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack -p 3003",
    "build": "next build"
  }
}

四个站共用一个 Next.js 版本,升级时一次升级全部,不存在「A 站还在 Next 14、B 站已经 Next 15」的漂移。代价是升级需要四站都回归一遍, 但静态导出站点的回归成本低(构建过 = 大概率没事)。

约定大于配置

同一件事在四个站里长得一模一样:

• output: 'export' 静态导出,images: { unoptimized: true };
• app/layout.tsx 里集中管理 SEO 元数据、OG 封面、结构化数据;
• sitemap.ts / robots.ts / not-found.tsx 三个基础设施文件齐全;
• 端口号写死在 dev script 里,3000 起,一个站一格。

约定带来的好处在改版时最明显:我知道任何一个文件的「对应物」在另外 三个站的哪个位置,AI 辅助改版时提示词都省了。

为什么不做组件级共享

最早考虑过把 Header/Footer/ShareBar 抽成 workspace 共享包,后来放弃了:

1. 四个站的品牌视觉完全不同,能共享的只有逻辑骨架,而骨架只有几十行;
2. 抽象包一旦改坏,四个站同时挂,耦合的爆炸半径反而变大;
3. 每个站代码量都不大(几百行),复用收益撑不起一层抽象的维护成本。

真正值得共享的是资产和流水线:PCB 的 STEP→GLB 转换脚本、OG 封面 生成脚本,这些放 shared/ 和 scripts/,谁用谁调,不产生运行时耦合。

一个 pnpm 特有的坑

pnpm 的 node_modules 是绝对路径 junction,某个包里有 node_modules 时 (比如 shared/pcb3d 自带依赖),webpack 的 FileSystemInfo 快照会把它 误处理,构建直接崩:

// next.config.ts — 按语义并入 managedPaths 跳过快照
config.snapshot.managedPaths = [
  ...(config.snapshot.managedPaths ?? []),
  /[\\/]scripts[\\/]pcb3d[\\/]node_modules/,
];

这类问题没有通用解,记住 pnpm 的 monorepo 里出现「莫名其妙的构建崩溃」, 先怀疑 junction 路径。

小结

monorepo 对「多个小站、一个人维护」的场景是明确的正解:依赖统一、 约定统一、部署统一。但要忍住两个冲动——不要过早抽共享组件包, 也不要为了让目录好看而引入构建复杂度。

总体链路

立创EDA STEP → step2obj.py (OCCT 三角化) → obj2glb.mjs (GLB)
            → gltf-transform 量化 → public/models/*.glb → <model-viewer>

分四步,每步一个独立脚本,串起来跑。

第一步:STEP 三角化,为什么不用 WASM

STEP 是 B-Rep 边界表示,浏览器渲染不了,先要三角化成网格。现成方案里 occt-import-js 提供 WASM 版的 OCCT,看似最省事,但实测对这种多层板 STEP 会输出空网格,问题出在它的 WASM 构建裁剪了部分几何内核能力。

最后用的本机 Python + cadquery-ocp(完整 OCCT 绑定)做三角化, 顺带解决另一个需求:按层名配色。

# step2obj.py 核心逻辑(节选)
from OCP.STEPControl import STEPControl_Reader
from OCP.BRepMesh import BRepMesh_IncrementalMesh

reader = STEPControl_Reader()
reader.ReadFile("board.step")
reader.TransferRoots()
shape = reader.OneShape()
BRepMesh_IncrementalMesh(shape, 0.3, False, 0.5, True)

PCB 的丝印层、阻焊层、基板在 STEP 里是不同颜色的实体,三角化后按颜色 拆分材质写入 OBJ,后面 glTF 转换时会自然映射成多个 primitive。

第二步:OBJ → GLB

这步没有技术含量,obj2gltf 一行命令,写成脚本只是因为要处理贴图路径和 缺省参数。GLB 比 OBJ+MTL 好在单文件、二进制、带 PBR 材质。

第三步:量化,模型从 40MB 到 4MB

原始 GLB 转出来 40MB 左右,网页加载不能接受。gltf-transform 三连:

npx gltf-transform weld board.glb t.glb
npx gltf-transform prune t.glb t2.glb
npx gltf-transform quantize t2.glb board-q.glb

quantize 使用 KHR_mesh_quantization 扩展,把顶点属性从 float32 压到 int16,配合 weld 去重和 prune 清理,体积降到 4MB,视觉上几乎无差别。 <model-viewer> 原生支持这个扩展,不需要额外解码库。

另一个经验:导出前在 EDA 里隐藏小元件(0402 电阻电容之类)的 3D 模型, 源文件体积直接砍半——这些元件在客户视角下本来也看不清。

第四步:网页端

展示组件直接用 @google/model-viewer,自托管它编译好的单文件, 不依赖运行时 CDN:

<model-viewer
  src="/models/board.glb"
  camera-controls
  auto-rotate
  shadow-intensity="1"
  style="width:100%;height:480px">
</model-viewer>

相比自己写 Three.js,model-viewer 把相机惯性、AR 入口、无障碍这些都 处理好了。如果后续要做「点击元件高亮 BOM」这类深度交互,再换 Three.js 也不迟——模型和管线都是复用的。

小结

整条管线写成三个脚本,换新板子就是「导出 STEP → 跑脚本 → 加一条记录」, 非前端同事也能自己发新版。