在 Travis CI 上自动部署 Jekyll

您可以针对一个或多个 Ruby 版本测试网站构建。

本指南将向您展示如何在 Travis 上搭建一个免费的构建环境，并与 GitHub 集成，以支持 Pull Request 自动测试。

1. 启用 Travis 与 GitHub

要为您的 GitHub 仓库启用 Travis 构建：

访问您的 Travis 个人主页：https://travis-ci.org/profile/username
找到您希望启用构建的仓库。
打开仓库对应的开关，使其变为蓝色。
（可选）点击齿轮图标配置构建选项。更多配置将通过 .travis.yml 文件完成，详见下文。

2. 测试脚本

最简单的测试脚本是运行 jekyll build，并确保 Jekyll 能够成功构建网站。

虽然这种方式不会检查最终生成的网站内容，但可以确认网站能够正常构建。

如果需要验证 Jekyll 的输出结果，html-proofer 是目前最合适的工具。

该工具会检查生成的网站，确保所有链接和图片均有效存在。

您可以：

使用 htmlproofer 命令行工具
编写 Ruby 脚本调用该 Gem

将希望执行的命令保存到文件：

./script/cibuild

HTML Proofer 命令行方式

#!/usr/bin/env bash
set -e # 出现错误时立即终止脚本

bundle exec jekyll build
bundle exec htmlproofer ./_site

部分选项可以通过命令行参数指定。

更多参数请参考：

html-proofer README 文档
本地执行 htmlproofer --help

例如，如果希望跳过外部网站链接检测，可使用：

bundle exec htmlproofer ./_site --disable-external

HTML Proofer Ruby 库方式

您也可以在 Ruby 脚本中调用 html-proofer（例如在 Rakefile 中）：

#!/usr/bin/env ruby

require 'html-proofer'

HTMLProofer.check_directory("./_site").run

配置选项作为 .new 的第二个参数传入，并使用以 Symbol 为键的 Ruby Hash。

有关全部配置项，请参考 html-proofer 的 README 文档。

3. 配置 Travis 构建

该文件用于配置 Travis 构建任务。

由于 Jekyll 基于 Ruby 开发，并依赖 RubyGems 安装相关组件，因此我们需要使用 Travis 的 Ruby 构建环境。

下面将展示一个示例 .travis.yml 文件，并解释其中每一行的作用。

注意：

您还需要提供一个 Gemfile 文件。

Travis 会根据 Gemfile 中声明的 Gem 自动安装依赖。

详情请参考： Travis Ruby Dependency Management

下面是一个简单的 Gemfile 示例，其中引用了 jekyll 和 html-proofer 两个 Gem：

```ruby id=”gemfile-example” source “https://rubygems.org”

gem “jekyll” gem “html-proofer”

您的 `.travis.yml` 文件应类似如下：
```yaml
language: ruby
rvm:
  - 2.6.3

before_script:
 - chmod +x ./script/cibuild # 或者在本地设置执行权限后提交到仓库

# 假设使用 Bundler，因此
# install 阶段默认会执行 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

这一行用于告诉 Travis 使用 Ruby 构建容器。

它会为你的脚本提供 Bundler、RubyGems 以及 Ruby 运行时环境的访问权限。

rvm:
  - 2.6.3

RVM 是一个常用的 Ruby 版本管理工具（类似 rbenv、chruby 等）。

该指令用于告诉 Travis 在运行测试脚本时使用哪个 Ruby 版本。

建议使用一个已预装在 Travis 构建 Docker 镜像中的版本，这样可以加快构建速度。

before_script:
 - chmod +x ./script/cibuild

构建脚本文件需要设置 可执行 属性，否则 Travis 会因为 permission denied 错误而失败。

你也可以在本地执行该操作并直接提交权限设置，从而使这一步变得不再必要。

script: ./script/cibuild

Travis 允许你运行任意 shell 脚本来测试你的网站。

一种常见约定是将项目中的所有脚本放在 script 目录下，并将测试脚本命名为 cibuild。

这一行配置是完全可自定义的。

如果你的脚本不需要频繁更改，也可以直接在这里写测试命令，例如：

install: gem install jekyll html-proofer
script: jekyll build && htmlproofer ./_site

script 配置项可以是任何合法的 Shell 命令。

# 分支白名单，仅用于 GitHub Pages
branches:
  only:
  - gh-pages     # 测试 gh-pages 分支
  - /pages-(.*)/ # 测试所有以 "pages-" 开头的分支

您需要确保 Travis 仅在包含您网站的分支上运行构建。

实现这一隔离的一种方式是在 Travis 配置文件中添加分支白名单。

通过指定 gh-pages 分支，可以确保相关测试脚本（如上所述）只会在站点分支上执行。

如果您使用 Pull Request 流程来提交更改，您可能希望为构建强制统一规范，例如将所有包含修改的分支加上前缀，如上例中的 /pages-(.*)/ 正则表达式。

branches 指令是完全可选的。如果省略该配置，Travis 将对仓库中的任意分支的每次 push 都执行构建。

请务必在 `_config.yml` 中排除 `vendor` 目录

Travis 会将 Gem 安装到 vendor 目录中。如果 Jekyll 读取到这些文件，可能导致构建失败或产生异常结果。

exclude:
  - vendor

为了提高构建速度，建议缓存 Bundler 下载的 Gem 包。

Travis 已经为 Bundler 提供了预设缓存策略：

cache: bundler

这样后续构建时无需重新下载全部依赖，可显著减少构建时间。

如果您不希望收到构建结果邮件通知，可以关闭邮件通知：

notifications:
  email: false

Travis 还支持多种通知方式，例如：

Slack
IRC
Webhook
HipChat
Discord（通过 Webhook）

您也可以根据需要选择其他通知渠道。

故障排查

Travis error: “You are trying to install in deployment mode after changing your Gemfile. Run bundle install elsewhere and add the updated Gemfile.lock to version control.”

Travis error: *“您正在以 deployment mode 安装，但在修改 Gemfile 之后出现了问题。请在其他环境中运行 bundle install，并将更新后的 Gemfile.lock 提交到版本控制中。

Workaround: Either run bundle install locally and commit your changes to Gemfile.lock, or remove the Gemfile.lock file from your repository and add an entry in the .gitignore file to avoid it from being checked in again.

解决方法：在本地运行捆绑安装并将更改提交到 Gemfile.lock，或从存储库中删除 Gemfile.lock 文件并添加 .gitignore 文件中的条目以避免再次签入。

有疑问？

本指南完全开源。

如果您发现错误或希望补充内容，欢迎直接编辑原文：编辑

如果在配置过程中遇到问题，也可以前往社区寻求帮助：

获取支持