Quarto+GitHub Actions报错：指定路径非网站项目及相关排查

编辑补充 #

问题与GitHub Token无关，而是与.qmd文件的存储路径定义有关，详见最后解答

问题背景 #

我用GitHub Actions搭建了每日自动更新的Quarto网站，此前运行正常，之后收到GitHub Token过期通知，执行Render and Publish步骤时出现报错：

The specified path (.) is not a website, manuscript or book project so it cannot be published.

报错出现在Quarto提供的以下脚本执行后：

git config --global user.email "quarto-github-actions-publish@example.com"
git config --global user.name "Quarto GHA Workflow Runner"
TARGET=""
if [ "$TARGET" == "" ]; then
  TARGET="gh-pages"
fi
if [ "true" != "true" ]; then
  quarto publish $TARGET . --no-render --no-browser
else
  quarto publish $TARGET . --no-browser
fi

报错看似与Token无关，但与Token过期同日出现，想了解如何更新Token？是否需要手动创建Token并存入仓库？因为初始配置时这一步是自动完成的。

完整的update.yaml配置（仅修改了cron部分）：

on:
  schedule:
    - cron: '*/20 * * * *'

jobs:
  update-report:
    runs-on: macos-latest
    permissions:
      contents: write
      pages: write
    steps:
      - name: Set up R
        uses: r-lib/actions/setup-r@v2

      - name: Install packages
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          packages: |
            any::tidyverse 
            any::janitor 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Check out repository
        uses: actions/checkout@v3
        
      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

解答 #

关于GitHub Token的问题 #

你配置中使用的${{ secrets.GITHUB_TOKEN }}是GitHub Actions自动生成的临时Token，有效期仅60分钟，不存在“过期需要手动更新”的情况——每次Workflow运行时都会自动生成新的Token。你收到的Token过期通知大概率和这个临时Token无关，可能是仓库中其他手动创建的Token（如之前添加的PAT）过期了。

如果确实需要手动创建Token（满足特殊权限需求），步骤如下：

• 登录GitHub，进入个人设置→Developer settings→Personal access tokens→Tokens (classic)
• 生成新的PAT，勾选repo、pages:write、contents:write等必要权限
• 进入目标仓库→Settings→Secrets and variables→Actions→New repository secret
• 命名为GH_TOKEN（或自定义名称，需与Workflow中的变量名对应），粘贴生成的PAT保存即可

实际报错原因：路径配置问题 #

根据补充信息，真正的问题是Quarto无法识别当前路径（.）为有效的网站/书稿项目，常见原因有：

1. 仓库根目录缺少_quarto.yml配置文件：Quarto项目必须通过该文件定义结构，无此文件则无法识别项目类型
2. .qmd文件存储路径错误：若内容文件不在根目录，需在quarto publish命令中指定正确路径（如项目在./docs下，需把.改为./docs）
3. _quarto.yml配置有误：未正确设置project.type为website、book或manuscript

解决方法：

• 确认仓库根目录存在正确配置的_quarto.yml，确保包含project.type字段，示例：

  project:
    type: website
  

• 若项目文件在子目录，修改Workflow中的quarto-actions/publish步骤，添加path参数指定项目路径：

  - name: Render and Publish
    uses: quarto-dev/quarto-actions/publish@v2
    with:
      target: gh-pages
      path: ./your-project-folder  # 替换为实际项目路径
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  

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