langxin11 · 学习笔记

本地配置与预览#

优先使用项目声明的包管理器，避免混用 npm 和 pnpm 生成两份锁文件。以 pnpm 项目为例，在 Windows PowerShell 中可以使用：

1
pnpm.cmd install
2
pnpm.cmd dev

随后完成三类配置：

1. **站点信息：**标题、作者、语言和公开网址。旧版 Mizuki 可能集中在 src/config.ts，其他版本可能拆分到 src/config/，以实际项目为准。
2. **内容：**文章通常位于 src/content/posts/；当前博客已采用独立内容仓库，需要通过对应同步流程接入主题。
3. **静态资源：**核对头像、文章图片和封面路径，并在本地预览中逐项检查。

不要把含 posts/ 的内容仓库直接当作 Astro 程序运行；实际构建入口位于主题/站点项目。

区分用户站点与项目站点#

Astro 的选项名是 site，不是 size。site 设置公开网址，base 用于指定子路径。用户站点部署在域名根目录时，一般不需要额外的 base：

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  site: 'https://你的用户名.github.io',
5
});

如果部署的是名为 my-blog 的项目站点，配置示例为：

1
export default defineConfig({
2
  site: 'https://你的用户名.github.io',
3
  base: '/my-blog',
4
});

以上仅展示相关选项，应合并到现有配置中，保留主题的 integrations 等设置。自定义域名或主题自动生成配置时，应以最终访问地址和主题入口为准。

配置 GitHub Actions#

下面按 2026-10-04 查阅的 Astro 官方部署示例更新 Actions 版本。旧文的 withastro/action@v3 和默认 Node 20 注释不应继续作为新建站点的当前配置；旧版本能否继续构建仍需结合项目验证。

示例适用于含 Astro 程序和锁文件的站点仓库。当前独立内容仓库还需要站点自己的内容同步步骤，以及内容更新后触发站点构建的机制；直接复制该工作流不会自动同步另一仓库的文章。Node 与包管理器应匹配主题要求，并提交相应锁文件。

1. 在站点项目的 .github/workflows/ 创建 deploy.yml：

   1
   name: Deploy to GitHub Pages
   2
   
   3
   on:
   4
     # 每次推送到 `main` 分支时触发这个“工作流程”
   5
     # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
   6
     push:
   7
       branches: [ main ]
   8
     # 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
   9
     workflow_dispatch:
   10
   
   11
   # 允许 job 克隆 repo 并创建一个 page deployment
   12
   permissions:
   13
     contents: read
   14
     pages: write
   15
     id-token: write
   16
   
   17
   jobs:
   18
     build:
   19
       runs-on: ubuntu-latest
   20
       steps:
   21
         - name: Checkout your repository using git
   22
           uses: actions/checkout@v7
   23
         - name: Install, build, and upload your site
   24
           uses: withastro/action@v6
   25
           # with:
   26
             # path: . # 存储库中 Astro 项目的根位置。（可选）
   27
             # node-version: 24 # 此版本 action 默认使用 24；若主题有其他要求，显式设置。
   28
             # package-manager: pnpm@指定版本 # 按项目锁定的版本填写；默认会检测锁文件。
   29
   
   30
     deploy:
   31
       needs: build
   32
       runs-on: ubuntu-latest
   33
       environment:
   34
         name: github-pages
   35
         url: ${{ steps.deployment.outputs.page_url }}
   36
       steps:
   37
         - name: Deploy to GitHub Pages
   38
           id: deployment
   39
           uses: actions/deploy-pages@v5

2. 在 GitHub 上，跳转到存储库的 Settings 选项卡并找到设置的 Pages 部分

3. 选择 GitHub Actions 作为你网站的 Source，然后按 Save。

4. 提交（commit）这个新的“工作流程文件”（workflow file）并将其推送到 GitHub

如果已经克隆自己的仓库，远程地址通常已经存在，可以先检查，再提交并推送本次改动：

1
git remote -v
2
git add .github/workflows/deploy.yml
3
git commit -m "配置 GitHub Pages 部署"
4
git push

工作流中的分支名应与实际发布分支一致。若改动了站点配置，也需要把对应文件纳入提交。构建成功后，继续检查首页、文章页、图片、公式、搜索和子路径链接，而不只看 Actions 是否变绿。