Nuxt 构建 56 秒:Nitro external 与真正有效的优化

2026-11-19 前端开发 有希 40 views

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 不是构建优化,但它解决另外两类问题:

  1. 首屏 JS 过大。只在浏览器运行的编辑器、图表、PDF 库,如果被服务端打包,会增加服务端 chunk 和启动时的模块解析;拆到客户端后,这部分代码只进入浏览器 bundle。
  2. 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

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles