将 Next.js 应用部署到 GitHub Pages

本博客是系列博客的一部分，我记录了如何使用 Next.js 框架重建一个依赖于 React.js 中的 HTML、CSS 和 Bootstrap 的网站，以提高性能、降低成本并增加我未来更改的工作流程。

2021 年更新：
我已将 Wallis Consultancy 从 GitHub Pages 迁移至 Vercel。我曾撰写过一篇文章，阐述了我的迁移动机，您可以点击此处阅读。本质上，Next.js 与 Vercel 的集成比与 GitHub Pages 的集成效果要好得多。
我保留了 Wallis Consultancy 在 GitHub Pages 上托管的版本，用于本博客，并更新了以下所有指向 Wallis Consultancy 的链接。
话虽如此，GitHub Pages 仍然是托管 Next.js 项目的好地方！

完成的网站（托管在 GitHub Pages 上）：https://james-wallis.github.io/wallisconsultancy/
源代码：https://github.com/james-wallis/wallisconsultancy

 简介

Wallis Consultancy 已完成在 Next.js 应用程序中的重新实现。这篇博文记录了将 Next.js 项目托管到 GitHub 页面的过程。内容包括：

• 用于next export将 Next.js 项目转换为静态网站。
• 构建 Travis 管道来构建网站并将其推送到gh-pages分支。

技术概述

GitHub 页面

GitHub Pages 是一种静态网站托管服务，它直接从 GitHub 上的存储库获取 HTML、CSS 和 JavaScript 文件，并可选择通过构建过程运行这些文件并发布网站。

GitHub 页面

特拉维斯

Travis CI 是一种托管的持续集成服务，用于构建和测试托管在 GitHub 和 Bitbucket 上的软件项目。

它对开源项目免费，并自动与 Github 集成。您只需注册并添加.travis.yml文件即可使用。

特拉维斯·CI

Next.js 导出

next export允许您将应用程序导出为静态 HTML，无需 Node.js 服务器即可独立运行。

它会将 HTML 生成到目录中。然后你就可以使用serveout等工具来运行你的应用了。

现在已经介绍了本博客中使用的技术，让我们将我们的 Next.js 应用程序部署到 GitHub Pages。

创建 Travis 构建

将 Travis 连接到 GitHub 仓库就像创建一个一样简单.travis.yml。以下内容记录了此过程以及如何在 Travis 构建中使用秘密环境变量。

1. .travis.yml在您的 Github 存储库的顶级目录中创建一个文件。
2. 添加以下内容（不包含注释）：

language: node_js # Node.js based project
node_js:
  - 12 # Level of Node.js to use
cache:
  directories:
  - node_modules # Cache the node_modules folder for quicker build times
script:
  - npm run build # Runs next build
  - npm run export # Runs next export and generates the out directory
  - touch out/.nojekyll # Creates a file telling Github not to build the project using Jekyll
deploy:
  provider: pages # Informs Travis this is a deployment to GitHub Pages
  skip_cleanup: true # Prevents Travis from resetting the working directory made during the build
  github_token: $github_token # GitHub access token to use when pushing to the gh-pages branch
  local_dir: out # Directory to push to the gh-pages branch
  on:
    # Only deploy when the build is on master or main branch - two common default branch names
    # If you're using a different branch name, add it here
    all_branches: true
    condition: $TRAVIS_BRANCH =~ ^(master|main)$

更多信息请参阅Travis Github Pages 官方文档

1. 一旦将其添加.travis.yml到存储库，您就需要将github_token（需要推送到gh-pages分支）变量添加到 Travis CI 设置中。

   1. 首先，按照创建个人访问令牌 - GitHub 文档中 的说明获取 API 令牌。注意：由于我的仓库在撰写此博客时是私有的，因此我启用了整个repo范围。不过，您也可以只启用该public_repo范围。 完整的 GitHub 仓库范围
   2. https://travis-ci.com/github/{your_username}/{your_repository}在浏览器中打开。
   3. 导航至更多选项 -> 设置。Travis 设置
   4. 在那里添加一个新的environment variable调用github_token，并使用你的访问令牌作为value。（可选）使其仅在主分支上可用。Travis 设置环境变量

2. 现在您已经设置好了 Travis 设置，.travis.yml可以开始您的第一个 Travis 构建了。只需将新代码发布.travis.yml到 master 分支，它就会自动启动。如果您已经完成此操作，请从 Travis-ci UI 启动 master 分支的新构建。

呼，配置了好多，不过总算完成了。接下来设置一下 GitHub Pages，这样网站就可以访问了。

设置 GitHub 页面

至此，Travis 构建应该已成功完成，并gh-pages在你的代码库中创建了一个分支。这意味着静态网站代码已可用，只需在 GitHub Pages 等地方提供服务即可。

您应该能够看到该gh-pages分支。

要为您的存储库启用 GitHub Pages，您需要：

1. 导航到 Github 存储库的设置选项卡（例如https://github.com/james-wallis/wallisconsultancy/settings）
2. 向下滚动到“GitHub Pages”部分。
3. 在源选项卡下选择gh-pages branch GitHub Pages 设置

过一会儿，你就可以通过 GitHub 提供的 URL 访问你的网站了（如果你无法回到上面的 Travis-CI 步骤）。以上就是使用 GitHub 页面托管静态网站所需的全部设置。

或者是...

有些不对劲... CSS 样式在哪里

如果您遵循上述两个部分，您将会看到您的网站就像在您的本地机器上一样。

相反，你看到的很可能是一个内容正确，但没有样式的网站。此外，如果你尝试在各个页面之间导航，它们将无法解析。它看起来会像下面这样：

不含 CSS 的 Wallis Consultancy 网站

你可能会问，为什么会发生这种情况？
Next.js 期望 CSS、JavaScript 文件和图片托管在 GitHub 上user.github.io/，但对于 GitHub 页面，网站将托管在子路径上，在我的情况下是这样user.github.io/wallisconsultancy。这导致网站无法找到任何依赖项或链接到其他页面。

您可以在本地重新创建它，方法是运行next export，然后使用serve来为输出目录的父目录提供服务（通常是out）。所以对我来说serve wallisconsultancy，输出目录是wallisconsultancy/out。

好的，但是我们可以修复它吗？

是的当然！

注意：如果您要使用自定义域名托管，则此问题将消失（只要您不使用像 GitHub Pages 这样的子路径）。请跳过本博客的其余部分，阅读我的下一篇博客：在 GitHub Pages 中使用自定义域名。

 Next.js assetPrefix 和 basePath 来帮忙

下一节将分为两个小节。第一小节将重点介绍如何使用 修复 CSS 样式和其他资源（例如图片）assetPrefix。第二小节将重点介绍如何修复指向不同页面的链接，首先使用环境变量作为路由前缀，其次使用Next.js 9.5basePath中引入的新配置变量。

修复 CSS 和其他资源

修复 CSS 和其他资产很简单，只需几个步骤即可完成：

1. 打开或创建next.config.js 文件。
2. assetPrefix在module.exports你的 GitHub 页面子路径中添加一个，并在两边各添加一个正斜杠。对我来说，这是：

module.exports = {
    assetPrefix: '/wallisconsultancy/',
}

通过这个简单的更改，您应该能够将该更改推送到 GitHub 页面，并能够看到您期望的页面布局。

修复页面之间的链接

Next.js 9.4 及以下版本
在 Next.js 9.5 之前，修复页面链接意味着修改<Link>已创建的每个页面，使其具有prefix。最简洁的实现方法是：

1. 打开或创建next.config.js 文件。
2. 添加一个名为的环境变量，BACKEND_URL其值为你的 GitHub Pages 子路径，并在开头添加一个正斜杠。对我来说，它是：

module.exports = {
    env: {
        BACKEND_URL: '/wallisconsultancy',
    },
}

1. 修改您的<Link>组件以使用前缀，方法是将其更改为：

<Link href={`${process.env.BACKEND_URL}${href}`}>{href}</Link>

因此，对于“关于”页面的链接href，<Link>

href="/about"

到

href={`${process.env.BACKEND_URL}/about`}

这有点混乱，但幸运的是，在 Next.js 9.5 中通过引入basePath变量简化了这一过程。

Next.js 9.5 及以上版本Next.js 9.5 引入了 basePath 变量，而不是在每个变量后面
添加一个。要使用它，您只需执行以下操作：BACKEND_URL<Link>

1. 打开或创建next.config.js 文件。
2. basePath在module.exports你的 GitHub 页面子路径中添加一个，并在开头添加一个正斜杠。对我来说，这是：

module.exports = {
    basePath: '/wallisconsultancy',
}

最终的next.config.js

结合assetPrefix和basePath我的next.config.js结果是：

module.exports = {
    basePath: '/wallisconsultancy',
    assetPrefix: '/wallisconsultancy/',
}

奖励：在next-optimized-images之前的博客文章
中，我介绍了下一个优化图像，它可以通过压缩图像来提高网站的性能。

为了修复 GitHub Pages 子路径问题，我在 my 中添加了imagesPublicPathnext.config.js变量。修复后，它现在看起来像这样：

const withPlugins = require('next-compose-plugins');
const optimizedImages = require('next-optimized-images');
module.exports = withPlugins([
  [optimizedImages, {
    mozjpeg: {
      quality: 80,
    },
    pngquant: {
      speed: 3,
      strip: true,
      verbose: true,
    },
    imagesPublicPath: '/wallisconsultancy/_next/static/images/',
  }],
  {
    basePath: '/wallisconsultancy',
    assetPrefix: '/wallisconsultancy/',
    env,
  },
]);

这样，我的网站就托管在 GitHub Pages 上了，看起来不错，而且我可以按预期在各个页面之间导航。现在，你可以向全世界任何人展示你的网站了！

这是 Wallis Consultancy 的链接，可以再次查看上述步骤的结果！

想要使用自定义域名吗？

围捕

在这篇博客中，我演示了如何构建 Travis 构建，它将构建你的 Next.js 应用程序并将其导出到静态网站。然后，我配置了 GitHub 页面来托管该网站，并修复了由于其托管网站的子路径导致的 CSS 和链接问题。

在本系列的下一篇也是最后一篇博客中，我将向您展示如何在 GitHub Pages 中使用自定义域。