返回

Next.js 打包部署至 GitHub Page 后：为何静态资源缺失导致样式失效？

前端

Next.js 项目部署到 GitHub Page 后静态资源缺失的故障排除指南

前言

Next.js 因其简便的语法和丰富的功能而备受前端开发者的青睐。而 GitHub Page 作为开源项目托管和展示平台也深受开发者喜爱。将 Next.js 项目部署到 GitHub Page 上，既能享受 Next.js 的开发便利，又可借助 GitHub Page 的便捷托管服务。不过，在部署过程中，你可能会遇到静态资源缺失，导致样式无法正常加载的问题。别担心，本指南将为你提供详尽的排查和解决指南，助你攻克此难题。

故障排查

1. 检查 Next.js 项目配置

首先，让我们检查一下 Next.js 项目的配置是否正确。打开项目根目录下的 next.config.js 文件，确保 publicRuntimeConfig 字段配置正确。此字段用于在构建时将环境变量注入到客户端代码中。

module.exports = {
  publicRuntimeConfig: {
    // 确保此处的 URL 与 GitHub Page URL 一致
    staticFolderUrl: 'https://example.github.io/static',
  },
};

2. 检查 GitHub Page 配置

接下来，我们需要检查 GitHub Page 的配置是否正确。在 GitHub 项目根目录下，找到 .github/workflows 目录，打开 deploy.yml 文件。确保 build 步骤中指定的构建命令和 deploy 步骤中指定的部署路径正确。

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run build

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v3
      - uses: JamesIves/github-pages-deploy-action@4.1.4
        with:
          branch: gh-pages
          folder: build
          clean: true

解决方法

1. 检查静态资源路径

现在，让我们来检查一下静态资源的路径是否正确。在 Next.js 项目中，静态资源通常存储在 public 目录下。确保你的静态资源位于此目录中，并且在代码中正确引用了这些资源。

2. 使用相对路径

为了确保静态资源能够被正确加载，建议你在引用静态资源时使用相对路径。例如，如果你想在页面中引入一个名为 logo.png 的图片，可以使用以下代码：

<img src="/logo.png" alt="Logo" />

3. 启用 GitHub Page 静态资源压缩

GitHub Page 提供了静态资源压缩功能，可以减少资源的大小，加快加载速度。要在你的项目中启用此功能，请在 .github/workflows/deploy.yml 文件中添加以下步骤：

- run: echo 'build/*' > public/staticfiles

- run: git add public/staticfiles

总结

现在，你已经掌握了排查和解决 Next.js 打包部署至 GitHub Page 后，静态资源缺失导致样式失效问题的技能。希望本指南能够帮助你快速解决问题，让你的网站重新焕发生机。请记住，在部署过程中遇到问题时，仔细检查 Next.js 项目配置和 GitHub Page 配置，使用相对路径引用静态资源，并启用 GitHub Page 静态资源压缩功能，可以帮助你避免许多常见问题。祝你开发顺利，再见！

常见问题解答

1. 如何检查 Next.js 项目配置是否正确？

打开项目根目录下的 next.config.js 文件，确保 publicRuntimeConfig 字段配置正确。

2. 如何检查 GitHub Page 配置是否正确？

在 GitHub 项目根目录下，找到 .github/workflows 目录，打开 deploy.yml 文件，确保 build 步骤中指定的构建命令和 deploy 步骤中指定的部署路径正确。

3. 如何检查静态资源路径是否正确？

确保静态资源位于 public 目录中，并且在代码中正确引用了这些资源。

4. 如何使用相对路径引用静态资源？

使用以下格式：/路径/到/资源，例如 /logo.png。

5. 如何启用 GitHub Page 静态资源压缩？

在 .github/workflows/deploy.yml 文件中添加以下步骤：

- run: echo 'build/*' > public/staticfiles

- run: git add public/staticfiles