使用 Jekyll 在本地测试您的 GitHub Pages 站点

您可以本地构建您的 GitHub Pages 站点以预览和测试对站点的更改。

谁可以使用此功能？

GitHub Pages 可用于具有 GitHub 免费版和 GitHub 免费组织版的公共仓库，以及具有 GitHub 专业版、GitHub 团队版、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。有关更多信息，请参阅“GitHub 的套餐”。

GitHub Pages 现在使用 GitHub Actions 来执行 Jekyll 构建。当使用分支作为构建的源时，如果您想使用内置的 Jekyll 工作流程，则必须在您的仓库中启用 GitHub Actions。或者，如果 GitHub Actions 不可用或已禁用，则将.nojekyll文件添加到源分支的根目录将绕过 Jekyll 构建过程并直接部署内容。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

平台导航

本文内容

任何拥有仓库读取权限的用户都可以本地测试 GitHub Pages 站点。

先决条件

在您可以使用 Jekyll 测试站点之前，您必须

安装 Jekyll。
创建一个 Jekyll 站点。有关更多信息，请参阅“使用 Jekyll 创建 GitHub Pages 站点”。

我们建议使用 Bundler 来安装和运行 Jekyll。Bundler 管理 Ruby gem 依赖项，减少 Jekyll 构建错误并防止环境相关的错误。要安装 Bundler：

安装 Ruby。有关更多信息，请参阅 Ruby 文档中的“安装 Ruby”。
安装 Bundler。有关更多信息，请参阅“Bundler”。

提示

如果您尝试使用 Bundler 安装 Jekyll 时看到 Ruby 错误，您可能需要使用包管理器（例如 RVM 或 Homebrew）来管理您的 Ruby 安装。有关更多信息，请参阅 Jekyll 文档中的“疑难解答”。

在本地构建您的站点

打开终端终端Git Bash。
导航到站点的发布源。有关更多信息，请参阅“配置 GitHub Pages 站点的发布源”。
运行bundle install。

在本地运行您的 Jekyll 站点。

$ bundle exec jekyll serve
> Configuration file: /Users/octocat/my-site/_config.yml
>            Source: /Users/octocat/my-site
>       Destination: /Users/octocat/my-site/_site
> Incremental build: disabled. Enable with --incremental
>      Generating...
>                    done in 0.309 seconds.
> Auto-regeneration: enabled for '/Users/octocat/my-site'
> Configuration file: /Users/octocat/my-site/_config.yml
>    Server address: http://127.0.0.1:4000/
>  Server running... press ctrl-c to stop.

注意

如果您已安装 Ruby 3.0 或更高版本（如果您通过 Homebrew 安装了默认版本，则可能已安装），您可能在此步骤中会遇到错误。这是因为这些版本的 Ruby 不再包含已安装的webrick。

要修复此错误，请尝试运行bundle add webrick，然后重新运行bundle exec jekyll serve。
如果您的_config.yml文件的baseurl字段包含您的 GitHub 仓库的链接，则可以在本地构建时使用以下命令忽略该值并在localhost:4000/上提供服务
```
bundle exec jekyll serve --baseurl=""
```

要在您的 Web 浏览器中预览您的站点，请导航至https://127.0.0.1:4000。

更新 GitHub Pages gem

Jekyll 是一个活跃的开源项目，经常更新。如果您的计算机上的github-pagesgem 与 GitHub Pages 服务器上的github-pagesgem 不一致，则您的站点在本地构建时可能与在 GitHub 上发布时有所不同。为避免这种情况，请定期更新计算机上的github-pagesgem。

打开终端终端Git Bash。
更新github-pagesgem。
- 如果您安装了 Bundler，请运行bundle update github-pages。
- 如果您没有安装 Bundler，请运行gem update github-pages。

进一步阅读

Jekyll 文档中的GitHub Pages