Nuxt3部署Firebase测试频道时CSS/JS文件404错误求助

问题概述 #

将Nuxt3（v3.1.1）项目通过Github Actions或本地CLI部署至Firebase Hosting时，出现页面请求的CSS/JS文件哈希与构建生成的哈希不一致的问题（例如构建生成entry.7c2ea9b2.js，页面却请求entry.37b79eda.js），导致大量资源404，页面显示异常。仅nuxt generate能修复静态页面问题，但动态路由仍存在同类错误。已尝试删除.nuxt、.output、.firebase/hosting.cache目录，执行npm cache clean --force均无改善，且长期使用同一机器部署的队友无此问题。

使用的构建命令：npx cross-env NITRO_PRESET=firebase npm run build，部署依赖Firebase官方Action或hosting:channel:deploy testing命令。

解决方案 #

1. 强制构建时禁用缓存并统一资源哈希规则

修改构建命令，明确禁用Nuxt和Vite的构建缓存，避免旧哈希记录干扰：

npx cross-env NITRO_PRESET=firebase NUXT_BUILD_CACHE=false VITE_CACHE=false npm run build

同时在nuxt.config.ts中添加资源输出配置，确保哈希生成逻辑一致：

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          assetFileNames: 'assets/[name].[hash][extname]',
          chunkFileNames: 'assets/[name].[hash].js',
          entryFileNames: 'assets/[name].[hash].js'
        }
      }
    }
  },
  nitro: {
    preset: 'firebase',
    output: {
      dir: '.output'
    }
  }
})

2. 调整Firebase Hosting缓存策略

在firebase.json中配置缓存规则，确保带哈希的资源长期缓存，而HTML文件强制不缓存（避免页面引用旧资源路径）：

{
  "hosting": {
    "public": ".output/public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "headers": [
      {
        "source": "**/*.@(js|css|png|jpg|jpeg|gif|svg|ico)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=31536000, immutable"
          }
        ]
      },
      {
        "source": "**/*.html",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=0, must-revalidate"
          }
        ]
      }
    ]
  }
}

3. 强制刷新Firebase测试频道缓存

部署测试频道时添加--force参数，强制覆盖旧缓存：

npx firebase hosting:channel:deploy testing --force

在Github Actions的部署步骤中同步添加force参数：

- uses: FirebaseExtended/action-hosting-deploy@v0
  with:
    repoToken: '${{ secrets.GITHUB_TOKEN }}'
    firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_DESK_APP }}'
    channelId: testing
    projectId: desk-app
    target: desk-app
    force: true

4. 确保环境依赖完全一致

队友机器无问题的核心原因是依赖版本统一，需锁定项目依赖版本：

• 提交package-lock.json到仓库（如果使用npm），确保CI和本地安装完全相同版本的依赖
• 在Github Actions中用npm ci替代npm install，避免依赖版本波动：

- run: npm ci && npx cross-env NITRO_PRESET=firebase NUXT_BUILD_CACHE=false VITE_CACHE=false npm run build

原因分析 #

1. 依赖版本差异：不同环境下Vite、Nitro等依赖的小版本不同，会导致Rollup生成的资源哈希值不一致
2. 构建缓存残留：Nuxt/Vite的构建缓存未彻底清除，复用了旧的哈希计算结果
3. Firebase缓存策略不合理：HTML文件被默认缓存，导致页面加载旧的资源引用路径，而带哈希的资源已更新
4. 测试频道缓存未刷新：Firebase测试频道默认保留旧部署缓存，未强制覆盖

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