Nuxt 构建 56 秒:Nitro external 与真正有效的优化
Nuxt 构建慢时,先别改配置。这个门户在闲置机器上的干净构建是 56–60 秒,之前看到的 136–187 秒来自后台残留进程抢 CPU,不是构建本身的成本。
先把基线测出来
2026-11-01 在同一台开发机上对同一个 Nuxt 4 门户做了两组干净构建,耗时分别是 60 秒和 56 秒,0 条警告。这个数字才是后续比较的基准。
项目是 Nuxt 4.6.4 + Nitro,构建命令在 package.json 里:
{
"scripts": {
"build": "node --disable-warning=DEP0155 node_modules/nuxt/bin/nuxt.mjs build"
}
}
Nuxt 4 的门户结构和普通 Nuxt 项目没有区别。构建慢的排查应该从默认流程开始,而不是先加一堆实验性开关。
136 秒不是配置成本
早期记录里出现过 136–187 秒,当时很容易得出“项目太重、必须大改”的结论。后来发现机器上还留着一个做 chunk 分析的后台进程,持续占用 CPU。把它结束后,同样的代码、同样的配置,构建回到 56–60 秒。
这类噪声在本地很常见:
- 上一次构建留下的 watcher、dev server 或 profiling 进程;
- 杀毒软件正在扫描
node_modules; - 同时开着浏览器、IDE 索引和 Docker;
- CI 机器上并发的其他任务。
所以看到异常数字,第一步不是改 nuxt.config.ts,而是确认测量环境。构建前用系统工具看一眼 CPU 占用:
Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 Name, CPU, Id
如果前几名里出现 node、esbuild、rolldown 或不知名的分析进程,先处理掉再测。Git Bash 里也可以用 time pnpm build 记录单次耗时,连续跑两次取稳定值,不要拿一次冷启动的结果下结论。
唯一明确的收益:关闭服务端压缩
这个项目真正减少构建时间的改动是 nitro.minify: false。Nitro 默认用 terser 压缩服务端产物,而门户大约有 480 个 chunk,单线程压缩要 20 秒以上。
服务端代码不经过网络传输,压缩只让磁盘上的文件小一点,对启动时间的影响在毫秒级。关掉它是明确的净收益:
export default defineNuxtConfig({
nitro: {
// 服务端产物不经过网络,terser 压缩换来的只是更小的磁盘占用
minify: false,
rollupConfig: {
onwarn(warning, rollupWarn) {
// 覆盖默认 onwarn 时,要保留 Nitro 自己的过滤规则
if (
['CIRCULAR_DEPENDENCY', 'EVAL'].includes(warning.code || '') ||
warning.message.includes('Unsupported source map comment')
) {
return
}
const fromDependency = /[\\/]node_modules[\\/]/.test(warning.id || '')
if (fromDependency && ['THIS_IS_UNDEFINED', 'INVALID_ANNOTATION'].includes(warning.code || '')) {
return
}
rollupWarn(warning)
}
}
}
})
onwarn 不负责提速,它只是把三方依赖自身的告警过滤掉,让构建输出回到 0 warnings。覆盖它时必须保留 Nitro 默认的过滤规则,否则那些本该忽略的告警会重新出现。
被高估的三件事
围绕“构建慢”最常见的三个建议,在这个项目里都实测过,结论和直觉不一样:
| 尝试 | 预期 | 实测结果 | 结论 |
|---|---|---|---|
把一个 118MB、34 个文件的模型静态目录移出 public/ | 少拷贝大文件,构建变快 | .output/public 从 158MB 降到 41MB,构建时间没有可测变化;静态拷贝只占 1–2 秒 | 只影响产物体积,不影响构建耗时 |
把重库页面改成 .client.vue | 减少服务端打包量 | 重库已经是 Nitro externals,对应 SSR chunk 只有 12–24KB,最多省个位数秒 | 价值在首屏 JS 和 SSR 边界,不在构建时间 |
设置 compatibilityDate | 影响 Nitro 行为 | 默认 node-server 预设下没有运行时效果,只消除“缺少日期”的警告 | 不是性能项 |
模型目录搬迁尤其容易误导:产物体积从 158MB 降到 41MB 很显眼,但静态文件复制是线性的磁盘操作,1–2 秒在 56 秒的构建里属于噪声。把它当成部署优化可以,当成构建优化就错了。
externals 已经替你做了
Nitro 默认会把适合在 Node 里直接 require 的依赖标记为 external,不打进服务端 bundle。这个项目的 .output/server/node_modules 里有 223 个包、约 20MB,模型运行时、中文转换、拼音、PDF、代码格式化、SQL 格式化、压缩器等大库都在其中。
所以“把大库从服务端挪走”并不能减少多少打包工作,因为服务端本来就没有把它们完整打进去。真正被打包的业务代码和框架代码才是构建时间的大头,而这部分不能靠 external 绕过。
可以用构建产物验证这一点:对比 .output/server/node_modules 的体积和 .output/server/chunks 里对应模块的大小。如果某个重库的 SSR chunk 只有几十 KB,说明它已经在 external 列表里,继续拆页面不会带来数量级的提升。
什么时候 .client.vue 仍值得
.client.vue 不是构建优化,但它解决另外两类问题:
- 首屏 JS 过大。只在浏览器运行的编辑器、图表、PDF 库,如果被服务端打包,会增加服务端 chunk 和启动时的模块解析;拆到客户端后,这部分代码只进入浏览器 bundle。
- SSR 不兼容。直接访问
window、document、localStorage的组件在服务端会报错,必须用.client.vue或ClientOnly隔离。
判断标准不是“这个库大不大”,而是“服务端是否需要执行它”。服务端不需要、浏览器必须执行的,拆;两边都要用的,留在共享代码里。拆完之后构建时间可能只变几秒,但首屏传输和运行时边界会更清楚。
怎么测才可信
一套可重复的测量流程比任何优化清单都重要:
# 1. 确认没有残留的高 CPU 进程(Windows 用 Get-Process,Linux/macOS 用 top)
# 2. 清理上一次的构建产物,保证是干净构建
rm -rf .output .nuxt/dist
# 3. 连续跑两次,取第二次或两次的平均值
time pnpm build
time pnpm build
需要记录的字段:
| 字段 | 为什么重要 |
|---|---|
| 机器负载 | 同一份代码在不同负载下能差出数倍 |
| 是否冷启动 | 第一次构建包含依赖预构建和缓存写入 |
| Node/pnpm 版本 | 不同版本的解析和压缩行为不同 |
| 警告数量 | 警告本身不慢,但大量警告往往意味着配置有问题 |
| 产物路径 | 区分 .output/public、.output/server 和 .nuxt |
如果 CI 比本地慢很多,优先看 CI 的 CPU 核数、缓存是否命中、是否每次都在重新安装依赖。构建配置通常不是第一嫌疑人。
FAQ
为什么第一次构建特别慢?
第一次要预构建依赖、生成类型和缓存,耗时明显高于后续构建。比较优化效果时,至少跑两次,拿稳定后的数字。
关掉 minify 会影响线上性能吗?
不会。Nitro 的 minify 只压缩服务端产物,服务端代码从磁盘加载,不经过浏览器网络。客户端 bundle 由 Vite 单独压缩,不受这个开关影响。
把大依赖改成 .client.vue 能提速吗?
在这个项目里最多省个位数秒,因为重库已经是 Nitro externals。它真正改善的是首屏 JS 和 SSR 兼容性,不要把两件事混在一起。
为什么 CI 上比本地慢很多?
先看 CPU 核数、依赖缓存和并发任务。CI 常见的瓶颈是每次全新安装依赖、共享 runner 被其他任务占用,而不是 Nuxt 配置。
构建时间多少算正常?
没有统一标准,只能和自己的基线比。这个门户在闲置开发机上是 56–60 秒;换机器、换 Node 版本后要重新建立基线。
小结
构建优化最容易犯的错,是在噪声数据上做决策。先把后台进程和机器负载排除,再测两次取稳定值,然后只保留有实测收益的改动。这个项目里明确的收益是关闭 Nitro 的服务端压缩;模型目录搬迁、.client.vue 拆分和 compatibilityDate 都不是构建提速项。配置改完可以用 代码格式化工具 检查缩进和语法,再回到同一套测量流程验证。更多前端工程化文章见 前端开发。
Comments
No comments yet — be the first to say something