如何解决Next.js项目执行npm run build时的缓存错误？

问题场景 #

执行npm run build生成生产构建时，出现RealContentHashPlugin缓存错误，CSS文件引用的字体资源（OTF/TTF）被标记为“不在编译中”，但开发模式（npm run dev）可正常运行。错误示例：

RealContentHashPlugin
发生了意外的缓存问题。
某资源被缓存时引用了另一个已不在编译中的资源（24b9e760）。
要么是资源被错误缓存，要么是被引用的资源也应从缓存中恢复。
引用来源：

• static/css/55b8cbc3b7204d90.css: .../_next/static/media/24b9e760aff7cc76-s.p.otf) fo...

解决方案步骤 #

1. 清理所有缓存 #

这是最直接的排查手段，清除旧的构建缓存和npm缓存：

• 删除Next.js构建缓存目录：

  # Linux/macOS
  rm -rf .next
  # Windows
  rd /s /q .next
  

• 清除npm缓存：

  npm cache clean --force
  

• 重新执行构建：npm run build

2. 验证字体资源的引入规范 #

确保CSS中字体的引用符合Next.js的资源处理规则：

• 字体文件应放在项目根目录的public文件夹下（比如public/fonts/）
• @font-face使用根路径引用，避免相对路径错误：

  @font-face {
    font-family: 'CustomFont';
    src: url('/fonts/custom-font.otf') format('opentype');
    font-weight: normal;
    font-style: normal;
  }
  

• 不要手动使用哈希后的资源路径，让Next.js自动处理资源哈希生成

3. 检查Next.js的webpack配置 #

如果自定义了webpack配置，可能干扰了资源处理逻辑：

• 临时注释next.config.js中的自定义webpack配置，重新构建测试
• 如果需要自定义字体处理，确保配置正确（兼容Next.js的资源处理）：

  module.exports = {
    webpack: (config) => {
      config.module.rules.push({
        test: /\.(otf|ttf)$/i,
        type: 'asset/resource',
        generator: {
          filename: 'static/media/[name].[hash][ext]'
        }
      });
      return config;
    }
  };
  

4. 排查依赖版本兼容性 #

版本冲突可能导致资源处理逻辑异常：

• 更新Next.js到最新稳定版：npm install next@latest
• 检查css-loader、mini-css-extract-plugin等依赖的版本，执行npm ls css-loader查看依赖树，解决版本冲突

5. 临时禁用webpack缓存（调试用） #

如果上述方法无效，可临时禁用webpack缓存排查：

// next.config.js
module.exports = {
  webpack: (config) => {
    config.cache = false;
    return config;
  }
};

构建完成后建议恢复缓存配置，避免影响后续构建速度

内容的提问来源于stack exchange，提问作者Benjamin Baumann