Astro部署GitHub Pages作品集失败：部署成功但访问提示文件未找到

1. 核对astro.config.mjs的基础路径配置 #

确保site和base参数与你的GitHub Pages地址完全匹配：

• 若你的站点地址是 <用户名>.github.io/<仓库名>，base必须严格设置为仓库名称（大小写也要一致）：

// astro.config.mjs
export default defineConfig({
  site: 'https://<用户名>.github.io',
  base: '/<仓库名>',
  // 其他配置项...
});

• 若为个人/组织主页（直接是 <用户名>.github.io），base可省略或设为'/'。

2. 确认GitHub Pages的部署源设置 #

进入仓库「Settings」→「Pages」：

• 若使用GitHub Actions部署，必须选择「GitHub Actions」作为部署源，而非「Deploy from a branch」
• 若之前尝试过手动用docs文件夹部署，需确保分支和目录选择正确，但使用Actions时此选项需切换为Actions

3. 检查deploy.yml的输出目录配置 #

Astro默认构建产物输出到dist文件夹，需确认Workflow中上传步骤指向正确目录：

# .github/workflows/deploy.yml 关键片段
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist # 此处必须与Astro构建输出目录一致，默认是dist

若你特意将产物输出到docs文件夹，需同步修改astro.config.mjs的outDir：

// astro.config.mjs
export default defineConfig({
  outDir: './docs',
  // 其他配置项...
});

同时Workflow中的publish_dir也要改为./docs。

4. 验证构建产物的结构 #

触发重新部署后：

• 进入仓库「Actions」→ 查看对应Workflow的「Build」步骤日志，确认文件生成在正确目录
• 检查自动创建的gh-pages分支，确认根目录下存在index.html等核心文件，路径与base配置匹配

5. 清除缓存并核对访问URL #

• 按Ctrl+Shift+R强制刷新浏览器，避免缓存旧内容
• 确认访问URL与site+base完全一致，例如仓库名为my-portfolio，需访问https://<用户名>.github.io/my-portfolio/（注意末尾斜杠）

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