AstroPaper 博客部署

本文记录我从 AstroPaper 原版项目开始，定制中文博客并部署到 GitHub Pages 的过程。最终采用两个仓库：一个保存 Astro 源码、文章和配置，另一个只保存构建生成的网站文件。

两个仓库分别做什么

源码仓库保存 Astro 项目本身：组件、配置、Markdown/MDX 文章、工作流等。它可以设为私有，用来保护尚未发布的稿件和项目源文件。

发布仓库保存 Astro 构建出来的静态文件，例如 index.html、_astro/、posts/、tags/ 和 pagefind/。GitHub Pages 从这个仓库的指定分支发布网站。

本例使用：

因为发布仓库名是 <用户名>.github.io，这是 GitHub 用户站点，网址是 https://wxcoding.github.io/，不需要额外的 /仓库名/ 路径。

获取 AstroPaper 源码

AstroPaper 原项目地址：satnaing/astro-paper。

可以先通过 Git 克隆原项目：

git clone https://github.com/satnaing/astro-paper.git wxblog
cd wxblog

如果你希望长期跟进上游更新，Fork AstroPaper 再克隆自己的 Fork，通常更容易比较上游变化。如果已经直接克隆了原项目，也可以添加上游远程地址：

git remote add upstream https://github.com/satnaing/astro-paper.git
git remote -v

origin 用来指向自己的源码仓库，upstream 指向 AstroPaper 原项目。基于模板复制出来的仓库可能没有共同 Git 历史，因此不要未经检查就直接合并上游分支；升级时先比较新版文件，再选择性更新框架文件，并保留自己的文章、配置和翻译。

创建自己的源码仓库后，将 origin 指向它，并推送源码分支：

git remote set-url origin https://github.com/wxcoding/wxblog.git
git push -u origin master

如果你的远程仓库默认分支是 main，命令和工作流里的分支名也要统一改成 main。仓库名称或权限变化后，记得重新确认 origin 地址以及仓库的可见性。

中文化和个人配置

AstroPaper 已将许多界面文案集中在 src/i18n/lang/zh.ts，常见的导航、分页、文章操作和无障碍标签可以在这里翻译，不必逐个重写组件。

博客文章和页面内容放在：

• src/content/posts/：文章 Markdown 或 MDX 文件；
• src/content/pages/about.md：关于页面；
• src/pages/index.astro：首页欢迎语等直接写在页面组件中的内容。

站点名称、描述、网址、作者、时区、功能开关和社交链接集中在根目录的 astro-paper.config.ts。正式发布前，应替换站点网址、作者主页、社交账号和仓库编辑链接等模板示例。

调整 Astro 网站地址

用户站点仓库 wxcoding.github.io 对应根网址，因此 astro-paper.config.ts 中应填写：

site: {
  url: "https://wxcoding.github.io/",
  // 其他站点信息
}

astro.config.ts 不需要设置项目站点常见的 base: "/repo-name"。如果改用 wxcoding.github.io 以外的项目站点仓库，部署地址会带仓库路径，届时必须重新设置 base，并验证静态资源、站内链接和 Pagefind 搜索路径。

创建发布仓库

在 GitHub 创建公开仓库 wxcoding/wxcoding.github.io。仓库可以先是空的；若已经有分支或文件，部署时需要确认工作流将发布到正确分支。

如果目标是让访客看不到 Astro 源码，可以将源码仓库 wxcoding/wxblog 设为私有；发布仓库必须保持公开，或确保你的 GitHub Pages 方案支持私有仓库。公开发布仓库中只会放构建产物，不会放原始 Astro 组件和 Markdown 文件。

但是已发布的文章正文会出现在生成后的 HTML 页面中，前端资源和网页内容也可由访客查看。不要把私人笔记、草稿或机密信息放进参与构建的文章、配置或资源中。

创建跨仓库部署 Token

源码仓库中的 GitHub Actions 需要权限向发布仓库写入文件，因此需要 Fine-grained personal access token：

1. 在 GitHub 个人设置中打开 Developer settings → Personal access tokens → Fine-grained tokens，选择 Generate new token。
2. Resource owner 选择拥有发布仓库的账号。
3. 在 Repository access 选择 Only select repositories，只勾选 wxcoding.github.io。
4. 在 Repository permissions 中将 Contents 设为 Read and write；Metadata 保持默认只读即可。
5. 生成 Token 后立即复制并安全保存。完整 Token 通常只显示一次，不要写进源码或提交到 Git。
6. 回到源码仓库的 Settings → Secrets and variables → Actions，新建 Repository secret：
   • 名称：PAGES_DEPLOY_TOKEN
   • 值：刚复制的 Token

工作流通过 ${{ secrets.PAGES_DEPLOY_TOKEN }} 读取该密钥。Token 到期或撤销后，需要重新生成并更新 Secret。

GitHub Actions 自动构建和发布

工作流文件位于 .github/workflows/deploy-pages.yml。每次向源码仓库的 master 分支推送时，它会：

1. 检出源码；
2. 安装 pnpm、Node.js 和项目依赖；
3. 运行 pnpm run build，生成 dist/；
4. 将 dist/ 内容推送到公开仓库 wxcoding/wxcoding.github.io 的 master 分支。

工作流中的关键配置如下：

on:
  push:
    branches:
      - master
  workflow_dispatch:

permissions:
  contents: read

jobs:
  deploy:
    steps:
      # 检出、安装依赖并构建……
      - name: 发布到公开网站仓库
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
          external_repository: wxcoding/wxcoding.github.io
          publish_branch: master
          publish_dir: ./dist
          user_name: github-actions[bot]
          user_email: 41898282+github-actions[bot]@users.noreply.github.com

这里的 branches 是源码仓库的触发分支；publish_branch 是构建产物写入发布仓库的目标分支。它们在本例中都叫 master，但属于不同仓库，不能因为名称相同就认为它们是同一条分支。

配置的 user_name 和 user_email 用于设置自动部署提交的 Git 作者信息。该提交身份可以显示为 github-actions[bot]；真正的跨仓库写入权限仍由 Token 提供。如果构建产物没有变化，部署 Action 可能显示 nothing to commit，此时不会新建提交，也不会覆盖旧提交的作者显示。

配置 GitHub Pages 发布来源

进入发布仓库 wxcoding/wxcoding.github.io 的：

Settings → Pages → Build and deployment

将 Source 设置为 Deploy from a branch，然后选择：

• Branch：master
• Folder：/(root)

保存后，GitHub Pages 会从该分支的仓库根目录发布静态网站。工作流成功并推送文件后，访问：

https://wxcoding.github.io/

如何确认部署成功

1. 在源码仓库的 Actions 页面查看“构建并发布博客”工作流。
2. 确认“构建网站”和“发布到公开网站仓库”步骤都成功。
3. 打开公开仓库，确认根目录中有 index.html、_astro/、posts/ 等构建产物。
4. 在发布仓库的 Settings → Pages 查看 GitHub 显示的网站地址，再打开网站验证页面、文章、静态资源和搜索。

如果 Actions 显示成功但网页没有变化，先检查工作流日志中的目标仓库和推送分支，再检查 Pages 是否配置为从同一个分支的根目录发布。若报告权限错误，检查 Secret 名称、Token 是否过期，以及 Token 对发布仓库是否有 Contents: Read and write 权限。

featured 参数是什么意思

featured 是文章 frontmatter 的布尔字段，用来控制文章是否进入首页的精选文章区域：

featured: true

在这个项目中，首页通过 data.featured 将文章分成两组：featured: true 的文章显示在“精选文章”区域；未设置或设为 false 的文章进入“最新文章”区域。它不会让文章自动变成草稿、隐藏文章或改变访问权限。

本文设置了 featured: true，因此会显示在首页精选区。精选区没有通过这个字段自动限制篇数；想从精选区移除某篇文章，将它改为 featured: false 或删除该字段即可。

总结

这套部署方式将源码管理和网站发布分开：私有源码仓库负责写作、维护和构建，公开发布仓库只保存网站产物。日常只需在源码仓库的 master 分支更新内容，GitHub Actions 就会自动构建并发布。记住分支分别属于哪个仓库、Pages 发布来源是否正确，以及 Token 应只授予必要的目标仓库权限，就能更容易定位部署问题。