在 CircleCI 上自动部署 Jekyll

使用 CircleCI 构建、测试和部署 Jekyll 网站

使用 CircleCI（持续集成与持续交付工具）可以快速完成 Jekyll 网站的构建、测试和部署。CircleCI 支持 GitHub 和 Bitbucket，你可以通过开源仓库或私有仓库免费开始使用。

1. 在 CircleCI 上关注你的项目

要开始使用 CircleCI 构建你的项目，只需在 CircleCI 网站上“关注（follow）”你的项目：

访问“Add Projects”页面。
在左侧的 GitHub 或 Bitbucket 标签页中，选择一个用户或组织。
在列表中找到你的项目，然后点击右侧的“Build project”。
首次构建会自动开始。你可以在仓库根目录创建一个 .circleci/config.yml 文件，告诉 CircleCI 如何构建你的项目。

2. 依赖管理

对于 Jekyll 项目（无论是否使用 CircleCI），管理依赖最简单的方式是使用 Gemfile。

你通常需要在 Gemfile 中包含 Jekyll、本项目使用的 Jekyll 插件、HTML Proofer 以及其他所需的 gem。同时不要忘记将 Gemfile.lock 一并纳入版本控制。

下面是一个示例 Gemfile：

source 'https://rubygems.org'

ruby '2.7.4'

gem "jekyll"
gem "html-proofer"

    - step:
       run: bundle install

3. 测试

最基础的测试就是确认 jekyll build 是否能够成功运行。这是后续所有测试的前提条件，因为其他测试都依赖于已生成的网站内容。

因此，我们会在依赖安装完成后，通过 Bundler 运行 Jekyll：

    - step:
        run: bundle exec jekyll build

HTML Proofer

网站构建完成后，通常还需要进行测试，以检查 HTML 是否有效、链接是否失效等。

虽然有不少相关工具可用，但 HTML Proofer 是 Jekyll 用户中较为流行的选择。我们会在测试阶段使用一些常用参数来运行它。

有关所有可用参数，请查看 html-proofer 的 README，或者在本地运行 htmlproofer --help 查看帮助。

    - step:
        run: bundle exec htmlproofer ./_site --check-html --disable-external

完整的 `.circleci/config.yml` 示例文件

下面的 .circleci/config.yml 示例演示了如何将你的 Jekyll 项目部署到 AWS。

要使其正常工作，你首先需要配置 S3_BUCKET_NAME 环境变量。

workflows:
  test-deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build
          filters:
            branches:
              only: master
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

有疑问？

本指南完全开源。如果你发现需要修正的地方，欢迎直接编辑本文。

如果在使用过程中遇到问题并需要帮助，可以前往社区支持页面寻求帮助。

此外，CircleCI 也提供了一个在线社区，你可以在那里获取相关支持。