Jekyll 自动化部署实战：CI/CD 流水线与 Git post-receive hook 完整指南

Jekyll 自动化部署实战CI/CD 流水线与 Git post-receive hook 完整指南【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 是一个基于 Ruby 的博客型静态站点生成器jekyll build会把源码渲染为纯静态 HTML 产物天然适合自动化部署。本文以 Jekyll 官方部署文档为核心系统讲解两大自动化路径基于持续集成CI服务的构建、测试与发布流水线以及基于 Git post-receive hook 的服务端自动部署并深入仓库源码与官方配置样例给出可直接复制的完整配置。读完本文你将掌握在 GitHub Actions、Travis CI、CircleCI、Buddy、Razorops 等平台以及自建服务器上实现代码推送即发布的完整能力。自动化部署的本质一次构建处处发布Jekyll 的构建输出目录默认为_site这在 lib/jekyll/configuration.rb 的默认配置中有明确声明destination File.join(Dir.pwd, _site)。所谓自动化部署就是把这个生成静态站点的动作与把产物分发到托管环境的动作串成一条自动执行的流水线触发Git 仓库收到一次提交commit或推送push构建在干净环境中安装依赖并执行jekyll build或bundle exec jekyll build生成_site目录校验可选对构建产物运行 HTML/链接检查防止坏链接上线发布把_site内容同步到 Web 服务器、对象存储如 AWS S3或 Pages 类托管平台。官方文档提供了两种主流落地方案使用第三方 CI 服务以及自建 Git post-receive hook。下面分别展开。方案一使用 CI 服务自动化构建与部署CI持续集成服务会在你的 Git 仓库产生提交时自动运行脚本。你可以在脚本中依次完成构建站点、对产物运行测试、再部署到目标服务。Jekyll 官方文档收录了 5 家 CI 提供商的完整指南GitHub Actions 指南Travis CI 指南CircleCI 指南Buddy 指南Razorops CI/CD 指南它们的基本套路一致声明 Ruby 环境 →bundle install→bundle exec jekyll build→ 可选运行 html-proofer 校验 → 上传产物或推送发布。下面逐一给出关键配置。GitHub Actions完全掌控构建环境与 gem 集合GitHub Pages 自带 Jekyll 构建但运行在一个受限的沙箱环境只能使用白名单内的插件和主题。而 GitHub Actions 允许你完全掌控构建环境和 gem 集合是官方文档强烈推荐的方式其优势包括Jekyll 版本自由不再受 GitHub Pages 固定版本限制可以在 Gemfile 中锁定任意版本如gem jekyll, ~ 4.2插件无限制可以使用任何 Jekyll 插件包括放在站点_plugins目录下的自定义*.rb文件主题自由可以使用依赖新版 Jekyll 特性的主题工作流可定制通过 workflow 文件自定义构建步骤与环境变量日志清晰构建日志可视化便于调试依赖缓存ruby/setup-rubyaction 可以自动缓存已安装的 gem避免每次构建重新下载。官方示例站点由_config.yml、index.md和一个 Gemfile 组成其中刻意使用了 GitHub Pages 白名单之外的Jekyll 4 与第三方插件jekyll-timeago用来演示 Actions 的优势# _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设置步骤很简单在仓库Settings → Pages中把构建来源从 Deploy from a branch 改为 GitHub Actions再到Actions标签页新建 workflow搜索Jekyll并选择官方Jekyll模板注意不是 GitHub Pages Jekyll提交即可。此后每次推送到默认分支workflow 会自动构建并发布到 GitHub Pages构建状态可通过提交旁的符号或 Actions 标签页查看。需要注意两点若仓库同时提交了由旧版 Bundler 生成的Gemfile.lock可能引发兼容问题从经典流程迁移且仍想使用 GitHub 托管主题时可借助jekyll-remote-theme插件并在_config.yml中正确设置remote_theme: owner/repo_name。Travis CI多 Ruby 版本构建与 html-proofer 校验Travis CI 的优势在于可以针对一个或多个 Ruby 版本测试站点构建并与 GitHub 的 pull request 集成。先在 travis-ci.org 个人页面打开目标仓库的构建开关然后编写测试脚本与.travis.yml。最简单的测试脚本只验证jekyll build能成功。官方推荐用html-proofer进一步检查生成站点中的所有链接和图片是否存在既可用命令行工具也可用 Ruby 库#!/usr/bin/env bash # ./script/cibuild set -e # halt script on error bundle exec jekyll build bundle exec htmlproofer ./_site#!/usr/bin/env ruby # 在 Rakefile 等 Ruby 脚本中以库方式调用 require html-proofer HTMLProofer.check_directory(./_site).runhtmlproofer支持丰富的命令行开关例如bundle exec htmlproofer ./_site --disable-external可跳过外部站点的链接检查。配套的.travis.yml完整示例含逐行语义language: ruby rvm: - 2.6.3 before_script: - chmod x ./script/cibuild # 确保脚本可执行也可本地设置后随提交带上 # 使用 Bundlerinstall 阶段默认执行 bundle install script: ./script/cibuild # 分支白名单通常仅用于 GitHub Pages 分支 branches: only: - gh-pages # 测试 gh-pages 分支 - /pages-(.*)/ # 测试所有 pages- 前缀分支 addons: apt: packages: - libcurl4-openssl-dev cache: bundler # 缓存 bundler gem 包以加速构建 notifications: email: false # 可选关闭构建结果邮件通知各关键字段的作用language: ruby使用 Ruby 构建容器提供 Bundler、RubyGems 与 Ruby 运行时rvm指定测试脚本所用的 Ruby 版本尽量选用 Travis 构建镜像预装的版本以加快速度before_script中chmod x测试脚本必须有可执行权限否则会报 permission deniedscript可执行任意 shell 命令比如也可简化为install: gem install jekyll html-proofer加script: jekyll build htmlproofer ./_sitebranches可选的分支白名单不加则每个分支的每次推送都会触发构建cache: bundler缓存 gem 包加速后续构建。必须注意的坑Travis 构建服务器会把所有 gem 装进vendor目录而 Jekyll 会误读该目录导致构建报错因此务必在_config.yml中加入exclude: [vendor]。这一点与源码中的默认排除列表相印证——lib/jekyll/configuration.rb 内置的DEFAULT_EXCLUDES已经包含了vendor/bundle/ vendor/cache/ vendor/gems/ vendor/ruby/等路径。常见的报错You are trying to install in deployment mode after changing your Gemfile...的解决方法是本地执行bundle install并提交更新后的Gemfile.lock或删除Gemfile.lock并在.gitignore中忽略它。CircleCI从构建、测试到 AWS S3 发布的一条龙示例CircleCI 支持 GitHub 与 Bitbucket 仓库。在 CircleCI 网站 Add Projects 页面选择仓库并点击 Build project 后仓库根目录的.circleci/config.yml即可接管构建。依赖用 Gemfile 管理同时记得把Gemfile.lock纳入版本控制source https://rubygems.org ruby 2.7.4 gem jekyll gem html-proofer最基础的测试是在构建阶段运行bundle exec jekyll build在测试阶段运行bundle exec htmlproofer ./_site --check-html --disable-external。官方还提供了完整的部署到 AWS S3 的示例需先在 CircleCI 中设置S3_BUCKET_NAME环境变量version: 2.1 jobs: build: docker: - image: cimg/ruby:2.7.4 environment: BUNDLE_PATH: ~/repo/vendor/bundle steps: - checkout - restore_cache: keys: - rubygems-v1-{{ checksum Gemfile.lock }} - rubygems-v1-fallback - run: name: Bundle Install command: bundle check || bundle install - save_cache: key: rubygems-v1-{{ checksum Gemfile.lock }} paths: - vendor/bundle - run: name: Jekyll build command: bundle exec jekyll build - run: name: HTMLProofer tests command: | bundle exec htmlproofer ./_site \ --allow-hash-href \ --check-favicon \ --check-html \ --disable-external - persist_to_workspace: root: ./ paths: - _site deploy: docker: - image: cimg/python:3.9.1 environment: S3_BUCKET_NAME: YOUR BUCKET NAME HERE steps: - attach_workspace: at: ./ - run: name: Install AWS CLI command: pip install awscli --upgrade --user - run: name: Upload to s3 command: ~/.local/bin/aws s3 sync ./_site s3://$S3_BUCKET_NAME/ --delete --acl public-read workflows: test-deploy: jobs: - build - deploy: requires: - build filters: branches: only: master这个配置展示了完整的最佳实践用restore_cache/save_cache按Gemfile.lock校验和缓存 gem构建成功后把_site通过 workspace 持久化给 deploy 作业deploy 作业仅允许构建成功后在 master 分支触发用aws s3 sync同步产物。其中--delete会删除远端多余文件确保线上与_site完全一致。Buddy基于 Docker 的快速 CI/CDBuddy 是基于 Docker 的 CI 服务器支持 GitHub、Bitbucket、GitLab 仓库可云端使用也可私有化部署。在 Buddy 中选择仓库、创建 pipeline 并设置触发模式为 On every push 后Jekyll action 会在隔离的jekyll/jekyllDocker 镜像中执行jekyll build产物输出到/filesystem目录并可继续通过 FTP/SFTP 或 IaaS 服务发布。后续还能追加 Slack 通知、SSH 重启服务等动作。若偏好配置即代码把下面的buddy.yml推送到目标分支即可自动创建 pipeline- pipeline: Build and Deploy Jekyll site trigger_mode: ON_EVERY_PUSH ref_name: master actions: - action: Execute: jekyll build type: BUILD docker_image_name: jekyll/jekyll docker_image_tag: latest execute_commands: - chown jekyll:jekyll $WORKING_DIR - jekyll buildBuddy 自托管版本可部署在支持 Docker 的任何服务器上包括 Linux、Mac、AWS EC2、DigitalOcean 与 Microsoft Azure。Razorops原生容器化 CI/CD15 分钟上线Razorops 是容器原生的完整 CI/CD 平台从提交到生产环境一气呵成。用 GitHub/Bitbucket/GitLab 账号登录后创建 pipeline、选择 Jekyll 项目在仓库根目录添加.razorops.yaml并配置环境变量即可。每次推送到所选分支步骤会按 YAML 自动执行tasks: build-and-deploy: steps: - checkout # 构建 Jekyll 站点 - commands: - bundle install - JEKYLL_ENVproduction bundle exec jekyll build # 上传静态页面目录到 AWS S3 或 FTP # AWS 访问密钥需在 Razorops 仪表盘的项目 pipeline 中配置为环境变量 - commands: - aws s3 rm s3://$AWS_S3_BUCKET --recursive - aws s3 cp _site s3://$AWS_S3_BUCKET --recursive if: branch main注意这里用JEKYLL_ENVproduction设置生产环境变量用if: branch main限定发布步骤只在主分支执行。构建阶段产出默认的_site目录部署阶段可以定义任意命令把站点代码发送到 S3、FTP 等目标服务器。方案二Git post-receive hook 服务端自动部署如果你有服务器并且希望通过git push直接触发部署可以使用 Git 的 post-receive hook让远端服务器在每次收到推送后自动完成构建与发布。这是文档中给出的自托管方案全程无需第三方 CI。第一步准备部署用户与裸仓库首先创建一个拥有所有授权部署公钥位于authorized_keys文件的用户账号。然后登录服务器初始化一个裸 Git 仓库并启用 hooklaptop$ ssh deployerexample.com server$ mkdir myrepo.git server$ cd myrepo.git server$ git --bare init server$ cp hooks/post-receive.sample hooks/post-receive server$ mkdir /var/www/myrepogit --bare init创建的是一个不带工作目录的裸仓库bare repository适合作为服务端接收推送的仓库/var/www/myrepo是后续存放站点文件的 Web 根目录将作为 nginx 或 Apache 的站点目录。第二步编写 post-receive hook 脚本在hooks/post-receive文件中加入以下内容并确保服务器已安装 Jekyll#!/bin/bash -l # Install Ruby Gems to ~/gems export GEM_HOME$HOME/gems export PATH$GEM_HOME/bin:$PATH TMP_GIT_CLONE$HOME/tmp/myrepo GEMFILE$TMP_GIT_CLONE/Gemfile PUBLIC_WWW/var/www/myrepo git clone $GIT_DIR $TMP_GIT_CLONE BUNDLE_GEMFILE$GEMFILE bundle install BUNDLE_GEMFILE$GEMFILE bundle exec jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW rm -Rf $TMP_GIT_CLONE exit脚本逐行解读#!/bin/bash -l以登录 shell 运行确保加载用户环境变量如 rbenv/rvm 的 PATHGEM_HOME与PATH把 Ruby gem 安装到用户目录~/gems避免污染系统环境TMP_GIT_CLONE用于暂存仓库最新内容的工作目录GEMFILE指向暂存目录中的GemfilePUBLIC_WWWWeb 根目录git clone $GIT_DIR $TMP_GIT_CLONEpost-receive hook 中环境变量$GIT_DIR指向裸仓库克隆出可构建的工作副本BUNDLE_GEMFILE$GEMFILE bundle install基于工作副本的 Gemfile 安装依赖BUNDLE_GEMFILE$GEMFILE bundle exec jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW用-ssource与-ddestination参数指定源目录与输出目录把站点构建到 Web 根目录rm -Rf $TMP_GIT_CLONE构建完成后清理临时克隆保持服务器整洁。第三步本机配置远端并推送在任意需要具备部署权限的开发机laptop上执行laptops$ git remote add deploy deployerexample.com:~/myrepo.git之后只需让 nginx 或 Apache 指向/var/www/myrepo部署就简化为一条命令laptops$ git push deploy master推送完成后服务器会自动完成依赖安装、站点构建与文件更新git push即发布。部署后的产物去向与配置注意点无论走 CI 还是 hook最终被发布的对象都是jekyll build生成的_site目录。关于该目录与相关路径可以从源码确认以下事实默认输出目录为_site由 lib/jekyll/configuration.rb 的destination File.join(Dir.pwd, _site)决定可通过-d命令行参数或_config.yml中的destination覆盖默认排除清单lib/jekyll/configuration.rb包含Gemfile、Gemfile.lock、node_modules以及vendor/下各子目录这解释了为何 CI 环境中把 gem 装在vendor下会被 Jekyll 误读——exclude: [vendor]正是为兼容这类场景准备的构建成功与否是部署的前提CI 流水线中bundle exec jekyll build任一环节失败都会中断流水线配合 html-proofer 的链接与图片检查可有效防止带坏链接的站点上线。小结如何选择自动化部署方案追求零运维、零成本如果仓库托管在 GitHub 且满足平台约束优先考虑 GitHub Pages需要插件/主题自由时改用 GitHub Actions 构建后发布需要多 Ruby 版本验证、PR 集成与详细测试Travis CI 配置直观html-proofer 校验链路完整需要从测试到对象存储的一条龙流水线CircleCI 的 build deploy 双作业模式可以直接参考偏好 Docker 化、可视化 pipeline 或私有化部署Buddy 与 Razorops 均可在 1520 分钟内完成搭建自有服务器、希望推送即发布Git post-receive hook 方案不依赖任何第三方适合把 Web 根目录托管在 nginx/Apache 下的场景。无论选择哪条路径核心流水线都是提交触发 → 干净环境构建 → 校验产物 → 同步发布你完全可以依照本文的示例配置组合出自己的发布体系。若需要手动发布的兜底手段rsync、scp、FTP、S3 同步等可参考 Jekyll 手动部署指南若想了解各类第三方托管平台的接入方式可阅读 第三方部署平台列表。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考