如何通过GitHub Actions移动文件？JupyterBook PDF迁移问题

文件未移动的常见原因 #

• PDF未成功生成：先检查GitHub Actions日志里的「Build JupyterBook PDF」步骤是否报错。如果构建失败，_build文件夹里根本没有PDF文件，自然无法移动。常见的构建失败原因包括依赖缺失、JupyterBook配置错误等。
• 移动命令路径错误：确认JupyterBook生成的PDF实际路径。比如部分版本的JupyterBook会把PDF放在_build/html/_static/下，而非_build/pdf/。可以在移动步骤前添加ls -R _build/命令查看完整目录结构，再调整mv命令的源路径。
• 目标目录不存在：如果目标文件夹（比如docs/pdf）未提前创建，mv命令会执行失败。需要先通过mkdir -p 目标文件夹路径确保目录存在。

提交文件的完整流程 #

要让GitHub能看到移动后的PDF，需在GitHub Actions中添加提交推送步骤。以下是完整的示例配置（保存为.github/workflows/build-pdf.yml）：

name: 构建并推送JupyterBook PDF
on: [push]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 配置Python环境
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: 安装依赖
        run: |
          pip install --upgrade pip
          pip install jupyter-book pyppeteer

      - name: 构建PDF
        run: jb build . --builder pdf

      - name: 创建目标目录
        run: mkdir -p docs/pdf

      - name: 移动PDF文件
        run: mv _build/pdf/*.pdf docs/pdf/  # 根据实际生成路径调整

      - name: 提交并推送
        run: |
          git config --global user.name "GitHub Actions Bot"
          git config --global user.email "actions@github.com"
          git add docs/pdf/*.pdf
          git commit -m "自动更新JupyterBook PDF"
          git push
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

额外注意事项 #

• 检查项目根目录的.gitignore文件：_build/被忽略是正常的（构建产物通常无需追踪），但目标文件夹（比如docs/pdf）不能被.gitignore包含，否则提交后GitHub仍无法看到文件。
• 权限问题：推送时必须使用GITHUB_TOKEN，它是GitHub自动生成的密钥，无需手动配置，直接在env中引用即可。

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