将静态资源构建到Github Pages的docs文件夹失败问题排查

此前使用自定义域名的Github Pages，资源放仓库根目录，部署正常可访问。现在整理项目，根目录仅保留配置和源码，本地npm run build将产物打包到docs文件夹，已在Github Pages中修改配置为从docs文件夹部署（DNS检查已通过）。配置了Node.js CI Action执行构建流程，Action运行正常且构建后docs目录存在CNAME文件，但站点https://mylinks.space/无法访问，有以下疑问：

1. 使用docs文件夹部署静态站点是否与根目录效果一致？
2. 配置的CI Action是否会在Github Pages部署前执行？
3. 是否因部署目录变更导致CNAME文件需重新进行DNS传播？

问题解答 #

1. docs目录与根目录部署效果是否一致？ #

本质效果一致。Github Pages会将你指定的部署目录（无论根目录还是docs）作为站点的根目录来提供静态资源服务，只要docs目录内的文件结构、资源内容和之前根目录的完全对应，访问逻辑不会有任何差异。核心是确保docs里包含所有必要文件（如index.html、CNAME、静态资源等）。

2. CI Action是否会在Github Pages部署前执行？ #

你当前配置的CI Action不会自动关联Github Pages部署流程。这个Action仅在CI环境中完成了构建，生成的docs产物只存在于CI的临时运行环境中，并没有同步到远程仓库的docs目录下。而Github Pages的部署是基于远程仓库里指定分支的指定目录来拉取文件的，所以如果CI没有把构建后的docs推送到仓库，Pages部署时拿到的还是旧文件甚至是空文件，自然无法正常访问。

3. 是否是DNS传播导致站点无法访问？ #

大概率不是。你已经通过了DNS检查，说明域名解析配置本身是有效的。更可能的原因包括：

• CI Action未将构建好的docs目录推送到远程仓库，导致Pages部署时没有获取到正确的静态资源
• Github Pages的部署配置未生效，检查是否正确选择了「main分支的docs目录」，以及最近的部署记录是否成功
• 远程仓库的docs目录中没有构建产物（本地构建的docs不会自动同步到远程，需手动或通过CI推送）

修复建议 #

修改你的CI Action，添加将构建后的docs目录推送到远程仓库的步骤，确保Github Pages能获取到最新产物。示例修改后的Action配置：

name: Node.js CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run build --if-present
      # 添加推送docs目录到远程仓库的步骤
      - name: Push docs to main branch
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/
          git commit -m "Build and update docs [skip ci]"
          git push

同时需要在仓库的「Settings → Actions → General」中，将「Workflow permissions」设置为「Read and write permissions」，确保CI有推送代码的权限。

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