使用Travis CI部署Jekyll站点遇GitHub Pages通用构建错误求助

针对你遇到的Travis部署日志显示正常，但GitHub Pages弹出通用构建错误的问题，结合你因jekyll-assets无法使用GitHub Pages原生构建的背景，我整理了几个针对性的排查和解决方向：

1. 阻止GitHub Pages自动触发冗余构建 #

你通过Travis直接把构建产物部署到gh-pages分支后，GitHub默认会尝试对该分支执行原生Jekyll构建，这很可能和Travis的部署产物冲突，触发无明确提示的通用错误。

• 解决方案：在仓库根目录添加.nojekyll空文件，告诉GitHub跳过Jekyll构建流程，直接使用已生成的静态文件。
• 操作方式：可以本地创建该文件后提交到gh-pages分支，也可以在Travis的cibuild脚本里添加一行touch _site/.nojekyll，让构建时自动生成。

2. 验证GitHub Token的权限有效性 #

虽然Travis日志显示部署成功，但GITHUB_TOKEN可能存在权限不足或过期的情况：

• 检查Travis仓库设置里的GITHUB_TOKEN变量，确保它是带有完整repo权限的个人访问令牌（PAT）。
• 重新生成一个新的PAT，勾选repo权限后更新Travis的环境变量，再重新触发构建测试。

3. 确认Jekyll构建产物的完整性 #

jekyll-assets的资源处理可能存在隐性问题，导致Travis构建的产物不完整：

• 在cibuild脚本中添加日志输出，查看构建后的文件情况，方便排查资源缺失问题：

  # 在bundle exec jekyll build后添加
  echo "=== 构建产物目录内容 ==="
  ls -la _site
  echo "=== 检查assets资源文件 ==="
  ls -la _site/assets
  

• 对比本地执行bundle exec jekyll build生成的_site目录和Travis构建的产物，确认是否有缺失的编译后CSS/JS等资源。

4. 查看GitHub Pages的详细构建日志 #

GitHub的“通用构建错误”提示过于模糊，你可以尝试找到更具体的错误信息：

• 进入仓库的「Settings」→「Pages」页面，查看最近的构建记录，点击“Details”查看完整的构建日志，里面可能隐藏着文件缺失、权限异常等具体问题。

5. 调整Travis部署的分支策略 #

当前你设置Travis只在gh-pages分支触发部署，容易造成“源码分支和部署分支混淆”的问题：

• 建议将源代码放在main（或master）分支，让Travis监听该分支的更新，构建完成后再部署到gh-pages分支，避免分支角色冲突。
• 修改.travis.yml的branches.only为你的源码分支，同时调整deploy.on.branch为对应分支。

附你的当前配置参考：

.travis.yml #

language: ruby
rvm:
  - 2.3.3
before_script:
  - chmod +x ./script/cibuild
script: ./script/cibuild
branches:
  only:
    - gh-pages
    - /pages-(.*)/
env:
  global:
    - NOKOGIRI_USE_SYSTEM_LIBRARIES=true
sudo: false
deploy:
  provider: pages
  skip-cleanup: true
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: gh-pages

cibuild脚本 #

#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build

内容的提问来源于stack exchange，提问作者Trufa