本地开发命令#

安装依赖：

1
pnpm install

启动开发服务器：

1
pnpm dev

本地构建：

1
pnpm build

预览构建结果：

1
pnpm preview

包管理器版本#

项目指定：

1
{
2
  "packageManager": "pnpm@9.14.4"
3
}

并且有 preinstall 限制：

1
{
2
  "preinstall": "npx only-allow pnpm"
3
}

所以这个项目应该使用 pnpm，不要用 npm install 或 yarn install。

Node 版本#

GitHub Actions 使用：

1
node-version: 22

本地如果有多个 Node 版本，优先使用 Node 22。

查看：

1
node -v
2
pnpm -v

构建命令实际做了什么#

package.json 里：

1
{
2
  "build": "astro build && pagefind --site dist"
3
}

也就是说 pnpm build 会先生成 Astro 静态站点，再为 dist 生成 Pagefind 搜索索引。

如果只运行 astro build，页面可以生成，但搜索索引可能不是最新的。

GitHub Pages 部署方式#

当前正确方式是 GitHub Actions。

workflow 文件：

1
.github/workflows/deploy.yml

关键步骤：

1
- run: pnpm install --frozen-lockfile
2
- run: pnpm build
3
- uses: actions/upload-pages-artifact@v3
4
- uses: actions/deploy-pages@v4

GitHub 仓库设置里应该选择：

1
Settings -> Pages -> Build and deployment -> Source -> GitHub Actions

不要选择：

1
Deploy from a branch

否则 GitHub 可能会同时触发默认 Jekyll 构建，出现一个成功的 Astro workflow 和一个失败的 pages build and deployment。

GitHub Pages 出现 Jekyll 日志是什么意思#

如果日志里出现：

1
GitHub Pages: jekyll
2
Theme: jekyll-theme-primer
3
Source: /github/workspace/.
4
Destination: /github/workspace/./_site

说明 GitHub 正在把仓库根目录当成 Jekyll 站点构建。

这个项目是 Astro，不应该走 Jekyll。

解决方法是把 Pages Source 改成：

1
GitHub Actions

Cloudflare Workers 部署#

当前 Cloudflare Workers Static Assets 配置在：

1
wrangler.jsonc

核心配置：

1
{
2
  "name": "r-gc-github-io",
3
  "compatibility_date": "2026-05-20",
4
  "assets": {
5
    "directory": "./dist/",
6
    "not_found_handling": "404-page",
7
    "html_handling": "auto-trailing-slash"
8
  }
9
}

Cloudflare 构建命令：

1
pnpm run build

部署命令：

1
npx wrangler deploy

站点地址配置#

Astro 配置里：

1
site: "https://r-gc.github.io/",
2
base: "/",
3
trailingSlash: "always",

site 会影响 sitemap、RSS 等生成结果。

如果以后主域名完全切到：

1
https://blog.rgcdev.top/

可以考虑把 site 改成主域名。

常见排查命令#

本地构建：

1
pnpm build

检查生成页面：

1
find dist -maxdepth 3 -type f | sort

查看 GitHub Actions 配置：

1
sed -n '1,220p' .github/workflows/deploy.yml

查看 Cloudflare 配置：

1
sed -n '1,160p' wrangler.jsonc

查看 scripts：

1
node -p "require('./package.json').scripts"

注意事项#

Cloudflare Workers 和 GitHub Pages 是两套部署。

Cloudflare 当前是主站部署，GitHub Pages 可以作为备用和对照。

GitHub Pages 默认 Jekyll 构建失败，不代表 Astro workflow 失败；看绿色的 Deploy to GitHub Pages workflow 是否成功更关键。

新增笔记后，Pagefind 会在构建时更新搜索索引。