您应该将 Next.js 应用程序发布到 GitHub 页面

最近，我改进了 2048 Game 的开源版本，并决定将其迁移到 Next.js 和 React 18。现有游戏已发布到 GitHub Pages，没有任何自定义域。我正在考虑部署到 Vercel，但它会失去过去 3 年积累的 Google 自然流量。这意味着我需要尝试部署到 GitHub Pages，今天我将分享我学到的东西。

如果您想在阅读整篇文章之前看到最终结果，您可以在这里检查。

快速介绍

我将使用两个 GitHub 功能 – GitHub Actions 和 GitHub Pages。如果您还没有听说过它们，让我快速解释一下：

GitHub Actions就像可以在您的项目上执行任务的小工作流程。这就像有一个帮手，可以自动执行您告诉它做的事情。您可以使用操作来运行测试、进行质量检查或构建应用程序。就我而言，我使用此工作流程来自动化部署管道。

什么是GitHub 页面？将它们视为开发人员和开源项目的网络托管选项。您可以使用 GitHub Pages 分享您的作品集、托管开源项目的网站，或者只是发布您喜欢的项目（例如我的项目）。

现在让我们开始吧。

第 1 步 – 激活您的存储库的 GitHub 页面

为了发布我们的 Next.js 应用程序，我需要激活项目存储库的 GitHub Pages。您可以在“设置”选项卡中找到（下图中的 1），然后从左侧菜单中选择“页面” (2)，然后找到允许我们指定部署源的下拉菜单(3)。

现在您需要将部署源更改为GitHub Actions 。

从现在开始，您的项目就有了一个专门的页面。您只需在那里发布内容即可。

第 2 步 – 配置 Next.js 构建流程

在部署 Next.js 应用程序之前，更改构建输出非常重要。默认情况下，Next.js 使用 Node.js 来运行应用程序，这与 GitHub Pages 不兼容。

GitHub Pages 旨在托管静态文件，这意味着我们只能在那里发布 HTML、CSS、JavaScript（和其他静态文件）。因此，我们需要在 Next.js 中启用静态页面生成。

为此，您将更改输出模式以在next.config.js内export ：

 /** @type {import('next').NextConfig} */ const nextConfig = { output: "export", // <=== enables static exports reactStrictMode: true, }; module.exports = nextConfig;

现在，运行next build后，Next.js 将生成一个包含应用程序静态资源的out文件夹。在接下来的步骤中，我们将将此目录上传到 GitHub Pages。

第 3 步 – 修复丢失的图像

页面发布在域的子路径下，并以项目名称作为子路径。令人困惑？让我们以我的 2048 游戏的 URL 为例：

 https://mateuszsokola.github.io/2048-in-react/

Github 为我的用户创建了一个名为mateuszsokola （我的用户名）的专用子域。但该项目是在子路径下发布的，在我的例子中是/2048-in-react 。不幸的是，这将导致图像和样式丢失的问题。

默认情况下，Next.js 将所有静态资产映射到域。这意味着favicon.ico文件将解析为mateuszsokola.github.io/favicon.ico而不是mateuszsokola.github.io/2048-in-react/favicon.icon 。

为了解决这个问题，我们可以通过在next.config.js文件中添加basePath来设置路径前缀：

 /** @type {import('next').NextConfig} */ const nextConfig = { basePath: "/2048-in-react", // <=== here it is output: "export", reactStrictMode: true, }; module.exports = nextConfig;

就我而言，它是/2048-in-react因为我的项目名为2048-in-react 。
请记住在项目目录的开头包含 ( / )。

第 4 步 – 创建 Github 操作

Next.js 正在生成可以发布到 GitHub Pages 的部署工件。现在是时候设置 Github Actions 来发布它们了。我决定将部署分为两个单独的操作以提高可重用性：

setup-node操作将设置 Node.js 并安装所有依赖项。为 Node.js 设置提供独立操作将允许我将其重用于其他管道。例如，我有运行的管道代码检查器和测试。也许您还希望执行多个操作。

每次我们将代码合并到main分支时， publish操作将构建 Next.js 工件并将其发布到 GitHub Pages。

让我首先解释一下setup-node操作。这是代码：

 # File: .github/workflows/setup-node/action.yml name: setup-node description: "Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧" runs: using: "composite" steps: - name: Setup Node.js ⚙️ uses: actions/setup-node@v4 with: node-version: 20 - name: Cache dependencies ⚡ id: cache_dependencies uses: actions/cache@v3 with: path: node_modules key: node-modules-${{ hashFiles('package-lock.json') }} - name: Install dependencies 🔧 shell: bash if: steps.cache_dependencies.outputs.cache-hit != 'true' run: npm ci

重要提示：在项目的.github/workflows/setup-node目录中创建此文件。确保将其命名为action.yml 。

这个片段有什么作用？

1. 它创建了一个composite动作。 composite操作允许您将多个工作流程步骤捆绑到一个操作中。如果不清楚的话，一旦我们进入第二个动作，你就会明白了。

2. 它使用 Node.js 20 创建新的构建环境并安装项目依赖项。

这些是setup-node操作中最重要的部分。现在，让我们继续publish操作：

 # File: .github/workflows/publish.yml name: publish-to-github-pages on: push: branches: - main permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout 🛎️ uses: actions/checkout@v4 - name: Setup Node.js ⚙️ - Cache dependencies ⚡ - Install dependencies 🔧 uses: ./.github/workflows/setup-node - name: Setup Pages ⚙️ uses: actions/configure-pages@v4 with: static_site_generator: next - name: Build with Next.js 🏗️ run: npx next build - name: Upload artifact 📡 uses: actions/upload-pages-artifact@v3 with: path: ./out deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Publish to GitHub Pages 🚀 id: deployment uses: actions/deploy-pages@v4

在项目的.github/workflows目录中创建此文件。您可以根据自己的喜好命名该文件 - 我将其命名为publish.yml 。

它能做什么？

1. 每次将新代码推送或合并到main分支时都会触发此操作。

2. 它使用setup-node操作来设置环境。我在上一个动作中创建的composite动作。现在您知道如何将composite操作包含在其他操作中。

3. 该操作分为两个阶段：在第一阶段，正在构建 Next.js 应用程序。在第二阶段，第一阶段的工件上传到 GitHub Pages。

这些是部署管道中最重要的方面。我跳过了权限和并发设置，因为它们对于所有 GitHub Pages 部署都保持不变。

现在，操作已准备就绪，可以使用了。

提交和推送

提交更改并将其推送到main分支后，GitHub 将自动启动到 GitHub Pages 的部署。

要检查该流程，请导航到“操作”选项卡（下图中的 1），然后从左侧菜单中选择“发布到 github-pages”操作 (2) 。您将在屏幕上看到所有部署（它们称为工作流程）。

现在选择这些工作流程中的第一个，您将看到一个两阶段部署。在部署阶段，您可以在 GitHub Pages 上找到指向您网站的链接。

结论

Github Pages 不足以托管拥有数百万浏览量的网站。但它是托管您的作品集或开源项目网站的完美选择。

有许多免费选项可以托管我们的网站，例如 Vercel，但我想向您展示另一种选择。 GitHub Pages 是为开发人员构建的，我认为每个开发人员都应该熟悉它。

如果本文对您有帮助，请在您的社交媒体上分享。

您在哪里部署您的应用程序？总是维塞尔吗？

学习 React 18 和 Next.js

您对 React 或 Next.js 感觉不强？加入我在 Udemy 上的在线课程！我将通过创建一个功能齐全的 2048 游戏来帮助您开始使用 React。我相信创建游戏可以让学习变得更加有趣，并且您将有一些很酷的东西可以向您的朋友展示。

👇👇👇👇

🧑‍🎓 加入Udemy 上的 React 18 和 Next.js 课程– 仅限本周 80% 折扣。