如何自定义Nuxt构建流程，实现仅上传变更文件？

嗨，我之前在自己的Nuxt项目里也遇到过一模一样的问题——每次构建全量替换文件、缓存完全用不上，甚至改个小组件整个vendor哈希都变了。咱们一步步拆解问题，找到可行的解决办法：

一、先搞定「未变更文件哈希乱变」的根源 #

你遇到的核心问题其实是哈希值不稳定，这才导致缓存失效、必须全量替换。常见原因和解决办法：

• 依赖版本不稳定：如果你的package.json里用了^/~这类模糊版本号，每次构建可能拉取了依赖的补丁更新，哪怕代码没改，vendor chunk的哈希也会变。解决办法：用package-lock.json/pnpm-lock.yaml锁死所有依赖版本，构建时用npm ci代替npm install，禁止自动更新依赖。
• 构建上下文带动态内容：比如你在nuxt.config.js里注入了时间戳、环境变量这类随构建变化的值，会被打包进静态文件里导致哈希变化。检查下配置，把动态内容限制在非静态文件（比如服务端逻辑）里。
• 代码拆分粒度太粗：默认的splitChunks可能把多个模块打包成一个chunk，只要其中一个模块变了，整个chunk的哈希就会跟着变，得做精细化拆分。

二、配置稳定的哈希与精细化代码拆分 #

在nuxt.config.js的build选项里做如下配置，确保只有内容真的变了的文件才会更新哈希：

export default {
  build: {
    // 给静态文件加上contenthash，只有内容变化时哈希才会变
    filenames: {
      app: ({ isDev }) => isDev ? '[name].js' : '[contenthash].js',
      chunk: ({ isDev }) => isDev ? '[name].js' : '[contenthash].js',
      css: ({ isDev }) => isDev ? '[name].css' : '[contenthash].css'
    },
    // 精细化拆分代码，避免牵一发而动全身
    splitChunks: {
      // 把布局文件拆成独立chunk
      layouts: true,
      // 每个页面单独拆成chunk，页面间互不影响
      pages: {
        name: false, // 禁用统一命名，让页面用自身的contenthash命名
        chunks: 'all'
      },
      // 把不常变更的核心依赖（比如vue、nuxt、axios）单独拆成公共chunk
      commons: {
        name: 'commons',
        test: /[\\/]node_modules[\\/](vue|nuxt|axios)[\\/]/,
        chunks: 'all',
        enforce: true
      }
    },
    // 生产环境禁用sourcemap，减少构建时间和文件体积
    sourcemap: false,
    // 开启Nuxt的构建缓存，重复构建时跳过已编译的模块
    cache: true,
    // 并行构建加快速度
    parallel: true
  }
}

三、实现增量上传的具体操作 #

当哈希稳定后，就可以只上传变更的文件了：

• 用rsync做增量同步：本地构建完成后，用rsync工具对比本地dist目录和服务器上的文件，只同步有变化的内容。命令示例：

  rsync -avz --delete ./dist/ your-server-user@your-server-ip:/path/to/nuxt/dist/
  

  注意：--delete会删除服务器上本地已不存在的旧文件，确保本地dist是最新的再用这个参数。
• 静态站点用增量生成（SSG场景）：如果你的项目是用nuxt generate生成的静态站点，可以加--incremental参数，只重新生成内容有变化的页面：

  nuxt generate --incremental
  

  这样只会重构变更的页面，其他页面的哈希完全不变，直接复用缓存。

四、额外的缓存优化建议 #

• 服务器端设置缓存策略：在Nginx等服务器上，给带哈希的静态文件（比如*.js/*.css）设置长期缓存（比如1年），给index.html设置短缓存或不缓存。这样用户访问时，只有index.html会重新请求，其他缓存文件只要哈希不变就不会重新加载。
• 避免在全局模板中加动态内容：比如不要在layouts/default.vue里注入随构建变化的内容，否则整个布局的哈希会变，导致所有页面都被迫重新加载。

如果你的项目是Nuxt 3，那会更省心——它默认支持增量构建和稳定的contenthash，只需要确保nuxt.config.ts里的build.filename配置正确即可。

内容的提问来源于stack exchange，提问作者H DD