企业官网建设流程全解析

使用 GitHub Actions 构建并部署 Jekyll 站点：突破 GitHub Pages 白名单限制的完整指南

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll

本指南以 Jekyll 官方文档（docs/_docs/continuous-integration/github-actions.md）为主线，讲解如何利用 GitHub Actions 在 GitHub Pages 上构建并托管 Jekyll 站点，从而获得对构建环境、Ruby gem 依赖与 Jekyll 版本的完全控制。读完本文，你将掌握在 GitHub Pages 受限环境下使用任意 Jekyll 版本、任意插件与主题的完整配置流程，并能独立排查构建日志、管理部署状态。

为什么需要 GitHub Actions：GitHub Pages 的受限构建环境

在 GitHub Pages 上构建 Jekyll 站点时，站点默认在一个出于安全原因而受限的环境中运行。这个环境虽然内置了大量白名单插件与主题，让用户能快速搭建站点，但也意味着：

• Jekyll 版本被锁定：只能使用 GitHub Pages 官方指定的 Jekyll 版本，无法自由升级或降级；
• 插件受白名单约束：只有白名单内的插件才能加载，Gemfile中声明的第三方插件在构建时会被忽略；
• 主题能力受限：依赖较新 Jekyll 特性的主题无法在受限环境中正常工作。

在 GitHub Actions 出现之前，唯一的绕行方案是：在本地或其他环境完成构建，再把构建产物推送到仓库的gh-pages分支，由 GitHub Pages 直接托管静态文件。这种方式虽然可行，但把“构建”与“发布”割裂成两步，且本地环境依赖难以在团队中统一。

GitHub 随后提供了自家的 CI/CD 产品GitHub Actions，使 Jekyll 站点可以在完全可控的构建环境中完成build（构建）与 deploy（托管），这是官方推荐的主流方案。Jekyll 仓库自身的文档体系也在持续迭代这一指南，例如 History.markdown 中记录了多次针对 GitHub Actions 文档的改进（如 #8853、#9426、#9682 等）。

使用 GitHub Actions 的优势

对 gemset（Ruby 依赖集）的完全控制

• Jekyll 版本：可以不再受限于 GitHub Pages 提供的版本（见官方 Dependency versions 列表），而是使用任意想要的版本——例如当前仓库使用的 Jekyll4.4.1（见 lib/jekyll/version.rb），或直接在Gemfile中通过 git 指向仓库源码。
• 插件：可以使用任意 Jekyll 插件，无论其是否被 GitHub 白名单收录，包括放在站点_plugins目录下的任意*.rb文件。在本地/CI 构建中，Jekyll 会通过 PluginManager 的require_plugin_files方法加载_plugins目录中所有 Ruby 文件，并通过require_gems加载plugins配置项声明的 gem 插件，同时支持从Gemfile的:jekyll_plugins分组自动加载（见 PluginManager.require_from_bundler）。
• 主题：在不使用 Actions 的情况下虽然也可以自定义主题，但通过 Actions 构建后，还能使用依赖 Jekyll 新版本特性（如自定义_data、Sass 支持等）的主题。主题的加载由 lib/jekyll/theme.rb 的Theme类负责，它会按 gemspec 声明解析主题根目录，并自动加载其_includes、_layouts、_sass、assets、_data等子目录。

迁移提示：如果你正从经典流程迁移，但仍希望沿用 GitHub 托管的主题，可以使用jekyll-remote-theme插件，把主题所需的依赖（以前由 GitHub Pages 默认捆绑）补充进你的_config.yml与Gemfile，并在_config.yml中正确设置remote_theme: <owner>/<repo_name>主题仓库 slug。

工作流管理能力

• 定制化：通过创建工作流文件（workflow file）来运行 Actions，你可以指定自定义构建步骤、使用环境变量，自由编排构建流水线。
• 日志：构建日志全程可见，并可调整为 verbose 模式，排查错误远比黑盒的 GitHub Pages 构建直观。
• 缓存：ruby/setup-rubyaction 支持自动缓存已安装的 gem，无需每次构建都重新下载整个 bundle，显著加快构建速度。

前置准备：一个托管在 GitHub 的 Jekyll 项目

使用本方案的首要前提是：Jekyll 项目已托管在 GitHub 上。可以选择已有项目，或参照 快速开始指南 创建新站点后推送。

本文后续演示的站点结构极简，仅包含_config.yml、index.md与Gemfile三个文件：

# _config.yml title: "Jekyll Actions Demo"

--- --- Welcome to My Home Page {% assign date = '2020-04-13T10:20:00Z' %} - Original date - {{ date }} - With timeago filter - {{ date | timeago }}

# Gemfile source 'https://rubygems.org' gem "jekyll", "~> 4.2" group :jekyll_plugins do gem "jekyll-timeago", "~> 0.13.1" end

这个示例站点的两个关键点：

1. 使用 Jekyll 4 与第三方插件jekyll-timeago，二者目前均不在 GitHub Pages 的白名单内——这正是需要 Actions 的原因。jekyll-timeago插件的作用是描述某个日期距今多久，例如给定2016-03-23T10:20:00Z、当前时间为2020-04-13T10:20:00Z时，输出为4 years and 3 weeks ago。
2. Gemfile中:jekyll_plugins分组的作用：Jekyll 启动时会优先检测Gemfile并调用 Bundler 加载该分组的 gem（见 PluginManager.require_from_bundler 中Bundler.require(:jekyll_plugins)的实现），从而让jekyll-timeago过滤器在构建时可用。

注意（Gemfile.lock）：所用的 action 会负责安装 Ruby gems 与依赖。虽然这让用户配置更简单，但如果你的Gemfile.lock是由旧版 Bundler 生成的并一同提交到仓库，则可能遇到兼容性问题——请留意 lock 文件的 Bundler 版本。

配置 Action（Configuring the Action）

第一步：在仓库 Settings 中开启 GitHub Actions 部署源

1. 进入仓库的Settings标签页；
2. 点击Code and automation下的Pages；
3. 在Build and deployment下，把Source从Deploy from a branch改为GitHub Actions。

第二步：在 Actions 标签页创建 Jekyll 工作流

1. 进入仓库的Actions标签页；
2. 点击New workflow并搜索Jekyll；
3. 在Jekyll工作流（注意：不是“GitHub Pages Jekyll” 工作流）下点击Configure；
4. 检查生成的工作流文件内容后点击Commit changes。

工作流模板源自 GitHub 官方的 starter-workflows 仓库。提交后，该工作流文件会出现在仓库中，成为后续每次构建与部署的依据。

构建与部署：触发、监控与查看

触发构建

每当向默认分支推送本地改动时，工作流即被触发，构建随之开始。整个流程由工作流文件驱动：检出源码 → 使用ruby/setup-ruby安装并缓存 Ruby 依赖 → 执行jekyll build→ 将构建产物发布为 GitHub Pages 站点。

监控构建状态

可通过以下两种方式查看构建进度与错误：

• 按提交查看（View by commit）：在 GitHub 仓库首页，最近一次提交旁会出现状态符号（对勾 ✓ 或叉号 ✗）。悬停后点击details链接即可进入构建详情。
• Actions 标签页：进入仓库的Actions标签页，点击jekyll工作流标签查看。

如果一切顺利，所有步骤将显示为绿色，构建产物会被上传到 GitHub Pages。

查看线上站点

进入仓库的Deployments标签页，点击已部署的站点 URL 即可访问线上站点。

后续更新

需要修改站点时，只需提交并推送到默认分支，工作流会自动再次构建并部署，无需任何额外操作。这与 自动化部署总览 中描述的 CI 模式一致——GitHub Actions 是该页推荐的 CI 服务之一。

源码视角：Actions 如何绕过 safe 模式与白名单

理解 GitHub Pages 限制的本质，能帮助你更好地设计 Actions 工作流。Jekyll 的插件加载与“安全模式（safe mode）”直接相关，核心逻辑在 lib/jekyll/plugin_manager.rb：

• 白名单检查：plugin_allowed?方法返回!site.safe || whitelist.include?(plugin_name)（见 plugin_manager.rb#L77-L79）。即只有在safe 模式开启且插件不在白名单中时，gem 插件才不会被加载。GitHub Pages 的受限环境正是运行在 safe 模式下；而 GitHub Actions 构建环境中site.safe默认为false，因此任意插件均可加载。
• 本地插件加载：require_plugin_files在非 safe 模式下会通过Utils.safe_glob递归加载_plugins目录下的所有*.rb文件（见 plugin_manager.rb#L92-L99）。对应的测试用例位于 test/test_plugin_manager.rb，其中验证了_plugins目录扫描与插件目录可配置（plugins_dir）等行为。
• 主题依赖加载：require_theme_deps会读取主题 gemspec 声明的runtime_dependencies并逐一加载（见 plugin_manager.rb#L38-L46），配合 lib/jekyll/theme.rb 的runtime_dependencies方法，使 Actions 环境下的主题依赖能够被完整解析。

结论很清晰：GitHub Actions 之所以能构建任意 Jekyll 站点，是因为它运行在非 safe 模式、拥有完整 gem 安装能力（Bundler）与自定义 Ruby 版本的环境——这正是本地构建体验的云端复刻，也是它与 GitHub Pages 自带构建的本质区别。

总结

• GitHub Pages 默认构建环境受安全限制：Jekyll 版本固定、插件与主题受白名单约束；
• 传统变通方案是在别处构建后推送gh-pages分支，构建与发布分离、难以维护；
• GitHub Actions 提供“构建 + 托管”一体化方案：任意 Jekyll 版本、任意插件（含_plugins/*.rb）、任意主题均可使用，且具备可定制工作流、详细日志与 gem 缓存三大优势；
• 配置只需两步：Settings → Pages → Source 改为GitHub Actions；Actions → New workflow → 选择Jekyll模板并提交；
• 之后每次推送到默认分支都会自动构建并部署，通过 commit 状态、Actions 标签页与 Deployments 标签页即可全程监控；
• 从经典流程迁移时，可借助jekyll-remote-theme与remote_theme: <owner>/<repo_name>配置继续使用 GitHub 托管的主题。

Jekyll 自身的插件机制（safe 模式、白名单、Bundler 集成）决定了构建环境的能力边界，而 GitHub Actions 正是把控制权交还给开发者、让 Jekyll 完整能力得以发挥的官方推荐路径。

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll