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

使用 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 ActionsGitHub 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 的优势对 gemsetRuby 依赖集的完全控制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这个示例站点的两个关键点使用 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。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 版本。配置 ActionConfiguring the Action第一步在仓库 Settings 中开启 GitHub Actions 部署源进入仓库的Settings标签页点击Code and automation下的Pages在Build and deployment下把Source从Deploy from a branch改为GitHub Actions。第二步在 Actions 标签页创建 Jekyll 工作流进入仓库的Actions标签页点击New workflow并搜索Jekyll在Jekyll工作流注意不是“GitHub Pages Jekyll” 工作流下点击Configure检查生成的工作流文件内容后点击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 ActionsActions → 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考