GitHub Pages 是什么，以及这个博客是怎么部署的
用浏览器请求、Astro 构建、GitHub Actions 发布和分层排错四条链路，图解这个博客从源码到线上静态页面的真实部署原理。
本文目录 6 节 · 点击展开
这个博客没有常驻后端进程。它先由 Astro 把源码构建成静态文件，再由 GitHub Actions 把构建产物发布到 GitHub Pages；读者访问时，Pages 直接返回已经生成好的 HTML、CSS、JavaScript 和图片。
Astro 负责“生成”，GitHub Actions 负责“自动执行”，GitHub Pages 负责“公开托管”。
浏览器访问时，真正发生了什么
https://apexcheng.github.io/首页或文章地址成为一条 HTTPS 请求。
apexcheng.github.ioPages 按已经发布的站点版本查找对应文件。
HTML · CSS · JS · images浏览器下载资源并在本地完成页面呈现。
astro.config.mjs 没有服务端 adapter；当前部署链路以 Astro 静态构建和 Pages artifact 为核心。
GitHub Pages 有用户 / 组织站点和项目站点两类。用户站点仓库使用特殊名称 <owner>.github.io，默认地址位于域名根路径；项目站点默认位于 /<repository>/ 子路径。这个差异会直接影响 Astro 的 base。
Astro 怎样把文章变成可部署文件
src/content/posts/：Markdown / MDX 文章src/pages/：页面与静态路由src/components/：Astro 组件src/styles/：站点样式
index.html：入口页面articles/…/index.html：文章页_astro/…：编译后的 CSS / JS- 图片、字体、RSS 等公开资源
npm run buildpackage.json 当前映射为 astro build。
dist/项目没有覆盖 outDir，沿用 Astro 默认静态输出目录。
不提交 dist远端 Action 会基于同一提交重新安装、构建并上传产物。
npm run build 才是发布前最接近云端的一次检查。可复制的本地构建命令：
npm run build
npm run previewpreview 用于检查刚生成的静态产物，不是生产服务器。Astro 官方部署文档也将默认构建命令写为 npm run build、默认发布目录写为 dist，可参考 Astro 部署说明。
GitHub Actions 怎样完成自动发布
main 收到新提交时自动触发。
允许从 Actions 页面手动运行。
cancel-in-progress: false，进行中的发布不被新运行取消。
actions/checkout@v6把触发这次运行的仓库内容检出到 runner。
withastro/action@v6使用 npm 安装依赖、执行 Astro 构建并准备 Pages artifact。
静态构建产物这是 build job 交给 deploy job 的发布对象。
actions/deploy-pages@v5把上一任务的 artifact 发布到 github-pages environment。
https://apexcheng.github.io/成功运行会输出部署 URL；外部是否已更新仍需线上验收。
当前仓库的真实 workflow 是 .github/workflows/deploy.yml。它与 Astro 官方 GitHub Pages 指南 的两任务结构一致；GitHub 也把 “checkout → build → upload artifact → deploy-pages” 作为自定义 Actions 发布的标准链路，见 GitHub Pages 发布源说明。
site、base 和仓库名怎样共同决定地址
apexcheng.github.iosite：设置完整域名base：当前不配置- 页面和资源从根路径
/开始
aboutsite：仍是所属域名base：通常配置为/about- 内部链接必须带上项目子路径
export default defineConfig({
site: 'https://apexcheng.github.io',
devToolbar: {
enabled: true,
},
integrations: [mdx()],
});base: ‘/blog’/blog/_astro/…仓库改名、改为项目站点或接入自定义域名时，都要重新核对 site、base、Pages 设置和内部链接；不能只改其中一个。
Astro 官方说明明确指出：项目站点通常要把仓库名配置为 base，而当仓库名符合 <username>.github.io 时可以跳过。当前项目的 src/utils/paths.ts 还保留了 withBase()，因此内部地址不会把根路径写死。
从改文章到线上验收，应该按哪条操作链
正式文章位于 src/content/posts/；公开文章保持 draft: false 和 private: false。
npm test
npm run build测试负责已有规则，构建负责 MDX、路由和静态生成。
git add src/content/posts/my-new-article.mdx
git commit -m "更新文章"提交记录定义这次远端构建使用的源码版本。
git push origin main当前 workflow 监听 main；其他分支不会通过这条 push 规则自动部署。
先确认 build job，再确认 deploy job；绿色状态来自真实运行，不从 YAML 推断。
至少打开首页、目标文章和一个静态资源；必要时使用无痕窗口排除缓存。
证明这份源码能生成静态站点。
证明远端环境完成构建与部署。
证明路径、资源与内容对读者可用。
本文没有把 dist/ 加入提交命令，因为当前部署方式会在 GitHub runner 上重新构建。若将来改为分支目录发布，交付对象与操作链也必须随之调整。
部署失败时，怎样分层定位
MDX 语法、frontmatter、import、公开状态、文件名是否正确。
npm test目标文件 diff依赖是否可安装，路由和 MDX 是否能生成，dist/ 是否完整。
npm run build构建日志首个错误workflow 是否触发，build 是否上传 Pages artifact，deploy 是否获得所需权限。
Actions runbuild / deploy jobSource 是否为 GitHub Actions，site / base 是否匹配用户站点或项目站点。
Settings → Pages资源请求 URL部署 URL 是否是最新运行，页面和静态资源是否返回预期版本。
无痕窗口直接访问文章路径先查 L3：提交是否真的 push 到 main，workflow 文件是否存在且能被 GitHub 读取。
回到 L1 / L2：从日志第一个有效错误开始，不先改 Pages 设置。
优先查 L4：CSS / JS 请求路径是否多了或少了 base。
先查 L5，再核对 deploy 使用的 commit；不要把缓存问题误判为构建失败。
site指向https://apexcheng.github.io- 当前没有配置
base - workflow 监听 main 并支持手动触发
- build → deploy 依赖关系存在
- 仓库 Pages Source 当前是否为 GitHub Actions
- 最新 Actions run 是否成功
- 线上站点和目标文章是否已更新
- 桌面端与 390px 移动端是否无布局溢出
这套部署方式把内容生产、构建自动化和静态托管拆成了清晰的责任边界。对当前博客而言，最重要的不是记住某个 Action 版本，而是始终分清：源码在哪里、产物是什么、谁负责发布，以及失败证据来自哪一层。