使用 Jekyll 在本地测试 GitHub Pages 网站

具有存储库读取权限的任何人都可以在本地测试 GitHub Pages 站点。

先决条件

在您使用 Jekyll 来测试站点之前，您必须：

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

建议使用 Bundler 安装和运行 Jekyll。 Bundler 可管理 Ruby gem 依赖项，减少 Jekyll 构建错误和阻止环境相关的漏洞。 要安装 Bundler：

1. 安装 Ruby。 有关详细信息，请参阅 Ruby 文档中的安装 Ruby。
2. 安装 Bundler。 有关详细信息，请参阅 Bundler。

本地构建网站

1. 打开终端终端Git Bash。

2. 导航到站点的发布来源。 有关详细信息，请参阅“为您的 GitHub Pages 网站配置发布源”。

3. 运行 bundle install。

4. 在本地运行您的 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。

     如果您安装了 Ruby 3.2 或更高版本，则可能会看到其他与 gem 和方法缺失相关的错误，这是由于与 github-pages gem 的兼容性问题所致。 在这种情况下，应改为安装 Ruby 3.1.x 或更早版本。

   • 如果 _config.yml 文件的 baseurl 字段包含GitHub存储库的链接，则可以在本地生成时使用以下命令来忽略该值，并在 localhost:4000/ 上为站点提供服务：

     bundle exec jekyll serve --baseurl=""
     

5. 若要预览网站，请在 Web 浏览器中导航到 http://localhost:4000。

更新 GitHub Pages gem 包

Jekyll 是一个活跃的开源项目，经常更新。 如果您电脑上的 github-pages gem 版本落后于 github-pages 服务器上的 GitHub Pages gem，那么您的站点在本地构建时的显示效果可能会与发布到 GitHub 上时不同。 为避免这种情况，请定期更新计算机上的 github-pages gem。

1. 打开终端终端Git Bash。
2. 更新 github-pages 程序包。
   • 如果已安装 Bundler，请运行 bundle update github-pages。
   • 如果尚未安装 Bundler，请运行 gem update github-pages。

延伸阅读

• GitHub Pages 在 Jekyll 文档中