Nuxt 4 部署 GitHub Pages 静态资源 404 问题排查

#目录

一、问题发现
二、问题解决（邪修）
三、探索正道
四、遗憾收场

#一、问题发现

今天使用NuxtJS 4.1.2部署一个Github Page项目，使用的是NuxtJS官方给出的工作流模版，链接在这里：

.github/workflows/deploy.yml

# https://github.com/actions/deploy-pages#usage
name: Deploy to GitHub Pages
on:
  workflow_dispatch:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: corepack enable
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      # Pick your own package manager and build script
      - run: npm install
      - run: npx nuxt build --preset github_pages
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./.output/public
  # Deployment job
  deploy:
    # Add a dependency to the build job
    needs: build
    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source
    # Deploy to the github_pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    # Specify runner + deployment step
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

因为我没有使用自定义域名，所以我配置了

NUXT_APP_BASE_URL=/<repository>/ npx nuxt build --preset github_pages

工作流部署完成之后，兴冲冲地打开网站，发现网页的其他部分倒是正常显示了，所以配置的baseURL应该也是正确的，只是我的所有/public目录下的图片资源都没有办法正确加载，查看浏览器控制台报错如下：

显然这里静态资源的请求链接把我的仓库名给漏掉了，而明明我已经配置了app的baseURL。这显然不合理。

#二、问题解决（邪修）

先说对我的项目成功的方案，因为这个网站只有几个图片，所以我给所有图片手动加上了仓库名前缀，重新部署之后生效了。

由此引申出一个另一个邪修：手动修改public的目录映射，相当于统一给public目录下的资源添加了仓库名前缀

export default defineNuxtConfig({
  app: {
    baseURL: "/ChatbotPage/",
    head: {
      title: "",
    },
  },
 
  dir: {
    public: "/ChatbotPage/public",
  },
});

#三、探索正道

但显然这不是通用的方法，如果项目有大量的静态资源，一是手动修改并不现实，二是这样修改public映射会影响开发环境。于是我开始搜寻通用的解决方案：

我尝试根据官方文档配置runtime的baseURL，但是没有作用，因为我的样式等都可以正常加载，那么说明baseURL是生效的，只是对于/public目录下的资源，Nuxt恐怕有不同的处理方式，首先查看关于我配置的baseURL的部分的指南：

可以看到，app.baseURL应该只对于app/目录下的内容生效，而/public和/app是同级的，这里提到了runtimeConfig，尽管我在工作流文件中构建步骤已经加上了“NUXT_APP_BASE_URL=/<repository>/”，但还是打算尝试修改runtimeConfig，于是有了：

export default defineNuxtConfig({
  app: {
    baseURL: "/ChatbotPage/",
    head: {
      title: "",
    },
  },
});

这个旧配置，到新配置的修改：

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      baseURL: "/ChatbotPage/",
    },
    app: {
      baseURL: "/ChatbotPage/",
    },
  },
});

然而这并没有什么用：

在本地预览构建产物，发现图片加载都正常，所以基本可以排除Nuxt框架下的各种配置的问题了，只需要注意配置

app.baseURL为/<repository>/就可以了。

#四、遗憾收场

最终并没有能成功找到问题所在，只能定性到public目录或许处理方式有问题。

个人只能算一个前端菜鸟，在后面排查问题的过程中发现Github Page可能存在服务端缓存，但是没有时间等待缓存清楚重试了，遗憾告终。

Nuxt4部署Github Page，Public目录下静态资源404