Nuxt3部署GitHub Pages时.nojekyll文件无效问题求助

问题分析 #

你已在public目录添加.nojekyll文件，但执行nuxt generate后，构建产物dist/static目录仍生成下划线开头的chunk文件（如_plugin-vue_export-helper.x3n3nnut.js），导致GitHub Pages无法正常加载这类资源，网站运行异常。核心原因是Vite默认chunk命名规则会生成下划线前缀文件，即便有.nojekyll，仍可能出现资源路径解析问题，或是Git忽略规则阻止了此类文件上传。

解决方案 #

1. 修改Vite配置，避免生成下划线开头的静态文件 #

在nuxt.config.ts中添加Vite构建配置，强制自定义chunk文件名格式，去除下划线前缀：

export default defineNuxtConfig({
  // 保留你原有的所有配置内容
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'static/[name].[hash].js',
          chunkFileNames: 'static/[name].[hash].js',
          assetFileNames: 'static/[name].[hash].[ext]'
        }
      }
    }
  }
})

该配置会让所有构建生成的静态资源（JS、CSS、字体等）统一使用[name].[hash]的命名格式，不再出现下划线开头的文件名。

2. 确保.nojekyll文件被正确复制到构建产物根目录 #

执行nuxt generate后，检查dist文件夹根目录是否存在.nojekyll文件。若未自动复制，可手动将public/.nojekyll复制到dist/，或是在nuxt.config.ts的nitro配置中明确指定public资源的复制规则：

nitro: {
  preset: "github-pages",
  assets: {
    publicAssets: [
      {
        dir: "public",
        baseURL: "/",
        filter: () => true // 确保public目录下所有文件（含.nojekyll）都被复制
      }
    ]
  }
}

3. 检查Git忽略规则 #

查看项目根目录的.gitignore文件，确认是否存在忽略下划线开头文件的规则（如_*）。若有，需添加例外规则允许dist/static下的相关文件被提交：

# 保留原有忽略规则，新增以下例外
!dist/static/_*.js
!dist/static/_*.css

验证步骤 #

1. 执行nuxt generate重新构建项目
2. 检查dist/static目录，确认不再有下划线开头的文件
3. 推送dist目录到GitHub Pages对应的分支
4. 访问GitHub Pages站点，验证资源加载及网站运行正常

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