工程实践·第 02 篇

从 Astro 到 Cloudflare Pages:一次完整的个人博客部署记录

从 Astro 本地构建、GitHub 双仓库、私有文章合并,到 Cloudflare Pages、Deploy Hook 和腾讯云自定义域名的完整实战教程。

我一直希望拥有一个完全由自己控制的写作空间:界面可以定制,文章使用 Markdown 保存,代码可以公开,但未来文章不进入公开仓库。

本文记录了这个博客从本地开发、GitHub 管理、私有文章合并、Cloudflare Pages 部署,到腾讯云域名解析和 HTTPS 上线的完整过程,也包括实际遇到的问题和解决方式。

最终架构

最终方案由四部分组成:

公开代码仓库
colars/blog
     │
     ├── Astro 页面与样式
     ├── 构建脚本
     └── 少量公开文章

私有文章仓库
colars/blog-content
     │
     └── posts/*.md

Cloudflare Pages
     │
     ├── 拉取公开代码
     ├── 使用只读 Token 拉取私有文章
     ├── 执行 pnpm build
     └── 输出 dist

正式域名
blog.xieje.cn

这样公开代码可以被 Fork,但未来文章源码保存在私有仓库中,不会随公开仓库一起被 Fork。

需要明确的是:部署后的文章正文仍然是公开网页,可以被阅读、抓取和复制。这个方案保护的是文章源文件,不是内容访问权限。

一、技术栈和工具

本次使用的主要工具如下:

工具 用途
Node.js 22+ 运行 Astro、构建脚本和本地工具
pnpm 11 安装依赖、执行构建命令
Git 管理公开代码和私有文章仓库
Astro 7 生成静态博客
TypeScript 检查配置和脚本类型
Tailwind CSS 4 页面样式
Pagefind 生成静态全文搜索索引
GitHub 保存代码和私有文章
GitHub Actions 在私有文章更新后触发部署
Cloudflare Pages 构建和托管静态站点
Wrangler 查看 Pages 项目、部署和 Secret
腾讯云 DNSPod 管理自定义域名 DNS

本地开发时,先确认工具可用:

node --version
pnpm --version
git --version

项目要求的 Node.js 版本:

{
  "engines": {
    "node": ">=22.23.0"
  }
}

Cloudflare Pages 构建环境中设置了:

NODE_VERSION=22

二、初始化 Astro 博客

项目目录:

D:\Project\Blog

安装依赖:

cd D:\Project\Blog
pnpm install

项目的主要依赖:

{
  "dependencies": {
    "@astrojs/rss": "^4.0.19",
    "@astrojs/sitemap": "^3.7.4",
    "@tailwindcss/vite": "^4.3.3",
    "astro": "7.3.2",
    "pagefind": "^1.5.2",
    "tailwindcss": "^4.3.5"
  }
}

主要目录:

src/
├─ components/        # 可复用页面组件
├─ config/            # 站点和作者配置
├─ content/posts/     # 公开文章
├─ layouts/           # 页面布局
├─ pages/             # Astro 路由
├─ styles/            # 全局样式
└─ utils/             # 内容和路由工具

常用的 package.json 脚本:

{
  "scripts": {
    "content:sync": "node scripts/sync-content.mjs",
    "predev": "node scripts/sync-content.mjs",
    "dev": "node scripts/astro.mjs dev",
    "precheck": "node scripts/sync-content.mjs",
    "check": "node scripts/astro.mjs check",
    "prebuild": "node scripts/sync-content.mjs",
    "build": "node scripts/astro.mjs build && pagefind --site dist",
    "preview": "node scripts/astro.mjs preview"
  }
}

predev、precheck 和 prebuild 会在主要命令执行前自动合并文章,避免忘记手动同步。

三、配置站点域名

站点地址在两个位置保持一致。

astro.config.mjs:

export default defineConfig({
  site: "https://blog.xieje.cn",
  integrations: [sitemap()],
});

src/config/site.ts:

export const siteConfig = {
  title: "en 的个人随笔",
  url: "https://blog.xieje.cn",
  // ...
};

这两个地址会用于:

  • canonical URL
  • Open Graph 元信息
  • RSS
  • Sitemap
  • 文章结构化数据

如果只修改其中一个,线上 SEO 地址很容易出现不一致。

四、文章格式

每篇文章使用 Markdown,文章头信息示例:

---
title: "文章标题"
description: "一句文章摘要"
publishedAt: 2026-11-17
category: "工程实践"
tags: ["Astro", "部署"]
cover: "/images/cover-blog.svg"
featured: false
draft: true
---

核心字段:

字段 作用
title 文章标题
description 摘要和 SEO 描述
publishedAt 发布时间
category 分类
tags 标签
cover 封面图
draft 是否作为草稿排除

设置 draft: true 后,文章不会进入正式页面、RSS 和搜索索引。

五、公开文章与私有文章合并

公开文章保存在:

src/content/posts/

私有文章保存在另一个仓库:

colars/blog-content/
└─ posts/
   ├─ private-post.md
   └─ images/

构建时,两类文章会合并到:

.content/posts/

该目录已加入 .gitignore:

.content/
.env

同步脚本会先复制公开文章,再复制私有文章:

await rm(outputPostsDir, { recursive: true, force: true });
await mkdir(outputPostsDir, { recursive: true });
await cp(publicPostsDir, outputPostsDir, { recursive: true });

私有仓库通过 GitHub API 下载:

const apiUrl =
  `https://api.github.com/repos/${repository}/tarball/${encodeURIComponent(ref)}`;

const response = await fetch(apiUrl, {
  headers: {
    Accept: "application/vnd.github+json",
    Authorization: `Bearer ${token}`,
    "User-Agent": "en-personal-essays-build",
    "X-GitHub-Api-Version": "2022-11-28",
  },
  redirect: "follow",
});

如果公开文章和私有文章存在同名文件,构建会直接终止:

Private content conflicts with an existing public file

这样不会静默覆盖已有文章。

六、创建 GitHub 公开代码仓库

初始化 Git:

cd D:\Project\Blog
git init -b main
git remote add origin https://github.com/colars/blog.git

如果目标仓库已经有 LICENSE 或其他初始提交,不要强推。先把远端历史安全拉下来:

git fetch origin main
git pull --ff-only origin main

提交前执行检查:

pnpm check
pnpm build

提交并推送:

git add -A
git commit -m "feat: 初始化 Astro 个人博客"
git push -u origin main

之后每次修改公开代码,都可以继续使用普通提交和普通推送,不使用 --force。

七、创建私有文章仓库

创建私有 GitHub 仓库:

colars/blog-content

克隆到本地:

git clone https://github.com/colars/blog-content.git D:\Project\BlogContent
cd D:\Project\BlogContent

创建文章目录:

New-Item -ItemType Directory posts -Force
New-Item -ItemType File posts\.gitkeep -Force

添加 .github/workflows/deploy-cloudflare-pages.yml:

name: Deploy Cloudflare Pages

on:
  push:
    paths:
      - "posts/**"
  workflow_dispatch:

permissions: {}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Cloudflare Pages
        env:
          DEPLOY_HOOK_URL: ${{ secrets.CLOUDFLARE_DEPLOY_HOOK_URL }}
        run: |
          if [ -z "$DEPLOY_HOOK_URL" ]; then
            echo "::error::Missing CLOUDFLARE_DEPLOY_HOOK_URL repository secret."
            exit 1
          fi

          curl --fail --silent --show-error --request POST "$DEPLOY_HOOK_URL"

提交并推送:

git add .
git commit -m "chore: 初始化私有文章目录与部署工作流"
git push -u origin main

这个工作流只发送部署请求,不下载文章,也不会把文章复制到公开仓库。

八、创建只读 GitHub Token

在 GitHub 创建 Fine-grained personal access token。

配置:

Resource owner: colars
Repository access: Only select repositories
Repository: colars/blog-content
Contents: Read-only
Metadata: Read-only
Expiration: 180 days

只读 Token 不代表永久有效。账号权限变化、Token 过期、仓库被转移或 Token 被撤销后,都需要重新生成。

Token 只保存到 Cloudflare Pages 的加密环境变量中,不写入:

  • .env.example
  • README
  • Git 提交
  • 构建日志
  • 截图

九、配置 Cloudflare Pages

在 Cloudflare 中创建 Pages 项目:

Project name: en-blog-pages
Git provider: GitHub
Repository: colars/blog
Production branch: main
Framework preset: Astro
Build command: pnpm build
Build output directory: dist
Root directory: 留空

添加环境变量:

BLOG_CONTENT_REPO=colars/blog-content
BLOG_CONTENT_REF=main
CONTENT_REPO_TOKEN=<180 天只读 Token>
NODE_VERSION=22

其中 CONTENT_REPO_TOKEN 必须保存为 Cloudflare Secret,而不是普通明文变量。

构建命令只需要:

pnpm build

因为 prebuild 会自动执行:

node scripts/sync-content.mjs

成功的构建日志应该包含:

[content] Merged 0 private post(s) from colars/blog-content@main.
[content] Ready with 3 total post(s).

私有仓库暂时没有文章时,合并数量为 0 是正常的。

十、创建 Deploy Hook

Cloudflare Pages 的 Git 集成只监听公开代码仓库。私有文章仓库更新时,需要额外的 Deploy Hook。

在 Cloudflare:

Workers & Pages
→ en-blog-pages
→ Settings
→ Builds & deployments
→ Deploy hooks
→ Add

配置:

Name: blog-content-main
Branch: main

保存生成的 URL。这个 URL 本身相当于敏感凭据,不能公开。

在私有仓库添加 Actions Secret:

Settings
→ Secrets and variables
→ Actions
→ New repository secret

名称:

CLOUDFLARE_DEPLOY_HOOK_URL

也可以使用 GitHub CLI:

gh secret set CLOUDFLARE_DEPLOY_HOOK_URL `
  --repo colars/blog-content

命令会提示输入 Secret 值,不要把 Deploy Hook URL 直接写进 YAML 文件。

测试工作流:

gh workflow run deploy-cloudflare-pages.yml `
  --repo colars/blog-content `
  --ref main

查看执行结果:

gh run list --repo colars/blog-content
gh run watch <run-id> --repo colars/blog-content --exit-status

GitHub Actions 成功后,Cloudflare 会重新拉取公开代码和私有文章并部署。

十一、配置腾讯云自定义域名

Cloudflare Pages 子域名绑定流程必须按正确顺序执行:

  1. 先在 Cloudflare Pages 添加自定义域名。
  2. 再到腾讯云 DNSPod 添加 CNAME。

Cloudflare 中进入:

Workers & Pages
→ en-blog-pages
→ Custom domains
→ Set up a domain

填写:

blog.xieje.cn

然后在腾讯云 DNSPod 添加记录:

字段 值
主机记录 blog
记录类型 CNAME
线路类型 默认
记录值 en-blog-pages.pages.dev
TTL 600

记录值不要带:

https://

也不要在末尾添加 /。

回到 Cloudflare Custom domains 页面,等待状态变成:

Active

Cloudflare Pages 会自动签发 HTTPS 证书,不需要在腾讯云额外申请 SSL 证书。

十二、验证部署

检查 DNS:

Resolve-DnsName blog.xieje.cn

检查首页:

Invoke-WebRequest https://blog.xieje.cn/ -UseBasicParsing |
  Select-Object StatusCode

检查 canonical:

$response = Invoke-WebRequest `
  https://blog.xieje.cn/ `
  -UseBasicParsing

[regex]::Match(
  $response.Content,
  '<link rel="canonical" href="([^"]+)"'
).Groups[1].Value

预期结果:

https://blog.xieje.cn/

检查 RSS、Sitemap 和搜索:

Invoke-WebRequest https://blog.xieje.cn/rss.xml -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/sitemap-0.xml -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/search/ -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/pagefind/pagefind-ui.js -UseBasicParsing

Pagefind 搜索索引只在生产构建后生成。开发模式主要验证布局和写作流程,完整搜索需要使用:

pnpm build
pnpm preview

十三、实际遇到的问题

1. pnpm 忽略了 esbuild 构建脚本

构建前出现过:

ERR_PNPM_IGNORED_BUILDS
Ignored build scripts: esbuild

解决方式是只在项目中允许 esbuild:

pnpm-workspace.yaml:

allowBuilds:
  esbuild: true

然后重新安装:

pnpm install

2. Git 提示目录所有权异常

不同 Windows 账户访问同一个仓库时可能出现:

detected dubious ownership

确认目录确实属于自己后,可以添加安全目录:

git config --global --add safe.directory D:/Project/Blog

如果只是临时检查,也可以对单次命令使用:

git -c safe.directory=D:/Project/Blog status

3. 目标 GitHub 仓库不是空的

目标仓库原本已经有一个 LICENSE 初始提交。

错误做法是直接强推,因为它会覆盖远端历史。

正确方式:

git fetch origin main
git pull --ff-only origin main

确认远端文件后再提交本地代码。

4. 创建成了 Worker 而不是 Pages

Cloudflare Dashboard 中的 Workers 和 Pages 入口容易混淆。

检查 Pages 项目:

pnpm dlx wrangler pages project list --json

如果列表为空,但下面命令能找到项目:

pnpm dlx wrangler deployments list --name en-blog

说明创建的是 Worker,不是 Pages。

本项目最终使用的 Pages 项目是:

en-blog-pages

5. 私有仓库拉取返回 404

Cloudflare 构建日志:

Unable to download private content repository (404).

GitHub 对“没有私有仓库权限的 Token”通常返回 404,而不是 403。

需要检查:

  • Fine-grained Token 是否选择了 colars/blog-content
  • 是否授予 Contents: Read-only
  • Token 是否过期或被撤销
  • 资源所有者是否为 colars
  • Cloudflare 中的 Token 是否复制完整

6. Token 被保存成普通文本

Cloudflare Pages 环境变量有不同存储类型。CONTENT_REPO_TOKEN 应使用加密 Secret。

如果保存成普通文本,Dashboard 中能看到原值,存在泄露风险。

可以将 Secret 统一设置为:

secret_text

7. 私有文章更新不会自动触发 Cloudflare

Cloudflare Git 集成只监听公开代码仓库。

因此额外增加了:

私有文章仓库 push
→ GitHub Actions
→ Cloudflare Deploy Hook

Deploy Hook 必须创建在 Git 集成的 Pages 项目中,Direct Upload 项目不能按这个方式工作。

8. 先加 CNAME 导致 522

如果还没有在 Pages 项目中关联自定义域名,就先添加了 CNAME,访问可能返回:

522 Connection timed out

解决顺序必须是:

Cloudflare 添加自定义域名
→ 腾讯云添加 CNAME
→ 等待证书和域名状态 Active

9. pages.dev 地址仍然存在

绑定自定义域名后,原来的:

https://en-blog-pages.pages.dev

不会自动消失。

因此需要同步修改 canonical、RSS 和 Sitemap 的正式域名。如果要强制旧地址跳转,可以后续使用 Cloudflare Bulk Redirect。

10. 搜索页在开发模式下没有结果

Pagefind 依赖生产构建生成的索引文件。

开发时只运行:

pnpm dev

搜索索引可能不可用。

完整验证方式:

pnpm build
pnpm preview

十四、安全边界

当前方案需要注意以下事项:

  1. 只读 Token 仍有有效期,180 天后需要轮换。
  2. Deploy Hook URL 不能公开,只保存在私有仓库 Actions Secret 中。
  3. CONTENT_REPO_TOKEN 必须使用 Cloudflare Secret。
  4. .content/ 和 .env 不提交到 Git。
  5. 私有文章仓库不能设置成公开仓库。
  6. 部署后的文章正文是公开 HTML,不能阻止读者复制。
  7. 如果文章曾经进入公开 Git 历史,仅删除当前文件并不等于从历史中移除。

十五、最终验证清单

上线后逐项检查:

  • 首页返回 200
  • 文章详情页可以访问
  • 归档、标签和分类正常
  • canonical 使用正式域名
  • RSS 使用正式域名
  • Sitemap 使用正式域名
  • Pagefind 搜索资源返回 200
  • 私有文章可以合并进入构建
  • 私有文章推送后 Deploy Hook 成功触发
  • GitHub Actions 工作流执行成功
  • Cloudflare Pages 最新部署状态为 Active
  • Token 保存为加密 Secret
  • 公开仓库中没有新增私有文章源码
  • pnpm check 为 0 错误
  • pnpm build 成功生成 dist

最终站点:

https://blog.xieje.cn/

参考资料

← 上一篇一个人如何搭建稳定的内容工作流