这篇文章记录我用 Astro + AstroPaper + Cloudflare Pages 搭建个人博客主页的过程。整体方案很轻量：Astro 负责静态站点生成，AstroPaper 提供现成的博客主题，Cloudflare Pages 负责从 GitHub 仓库自动构建和部署。
Table of contents
Open Table of contents
为什么选择这套方案
之前我也尝试过 GitHub Pages + Jekyll。它足够经典，但我更想要一个现代一点、可定制性更高、前端体验更好的博客主页。Astro 的静态构建速度很快，写 Markdown 也舒服；AstroPaper 主题本身已经包含文章列表、标签、归档、搜索、暗色模式、RSS、站点地图等博客常用能力；Cloudflare Pages 则可以直接连接 GitHub 仓库，提交代码后自动部署。
最终效果可以参考我的站点：https://alex-loo.pages.dev/。
准备环境
本地需要先安装：
- Node.js
- pnpm
- Git
- GitHub 账号
- Cloudflare 账号
如果你还没有安装 pnpm，可以执行：
npm install -g pnpm确认安装成功：
pnpm -v创建 AstroPaper 项目
如果只是创建一个普通 Astro 项目，可以使用 Cloudflare 官方提供的命令：
pnpm create cloudflare@latest my-astro-app --framework=astro --platform=pages之后再添加 Cloudflare adapter：
pnpm astro add cloudflare不过我这次的目标是搭建博客，而不是从零开始搭一个普通 Astro 项目，所以直接使用 AstroPaper 主题模板：
pnpm create astro@latest --template satnaing/astro-paper我希望尽量使用作者的最新版本，所以实际操作时是从 AstroPaper 的 GitHub Release 下载最新版压缩包，然后解压到本地项目目录。本文写作时我使用的是 v6.0.0：
https://github.com/satnaing/astro-paper/releases/tag/v6.0.0
本地运行
进入项目目录后安装依赖：
pnpm install启动本地开发服务器：
pnpm dev浏览器打开终端里提示的本地地址，通常是：
http://localhost:4321如果能看到 AstroPaper 默认首页，说明本地项目已经跑起来了。
创建 GitHub 仓库
Cloudflare Pages 可以直接从 GitHub 仓库拉取代码并自动构建，所以需要先把本地项目推送到 GitHub。
在项目根目录执行：
git init
git remote add origin https://github.com/<your-gh-username>/<repository-name>
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main把 <your-gh-username> 和 <repository-name> 替换成你自己的 GitHub 用户名和仓库名。
部署到 Cloudflare Pages
进入 Cloudflare Dashboard，打开 Workers & Pages 页面，点击 Create application。
这里有一个我踩过的坑：创建时要选择 Pages，不要沿用默认的 Workers。我一开始一直在 Workers 里折腾，部署不成功后还以为是代码配置问题，最后才发现对于这种静态博客，Cloudflare Pages 才是更直接的入口。
简单理解一下两者区别：
- Cloudflare Pages 更适合静态站点和前端项目，比如 Astro、React、Vue、Svelte 等，可以从 GitHub 仓库自动构建并部署。
- Cloudflare Workers 更适合运行边缘函数和后端逻辑，比如 API、鉴权、请求转发、边缘计算等。
AstroPaper 这种博客站点优先选择 Pages 就可以。
接着选择 Import an existing Git repository。
授权 GitHub 后，选择刚才创建并推送的博客仓库。
进入配置页面后，按下面这样填写：
| Configuration option | Value |
|---|---|
| Production branch | main |
| Build command | pnpm run build |
| Build directory | dist |
Project name 可以自定义。它会影响 Cloudflare Pages 默认分配的 *.pages.dev 子域名，比如项目名是 alex-loo，默认访问地址就是 https://alex-loo.pages.dev/。
确认无误后点击 Save and Deploy。Cloudflare 会开始拉取 GitHub 仓库代码、安装依赖、执行构建，并把 dist 目录发布出去。
部署成功后可以看到成功提示和访问地址。
我的部署结果：
修改 AstroPaper 首页
AstroPaper 默认首页已经很完整，但我希望个人主页更有自己的风格，所以在主题基础上重新设计了 hero section。
我主要参考了 mxb.dev 的首页气质：页面更像一个个人空间，而不只是文章列表入口。
这次 hero section 的改造我只修改了 src/pages/index.astro。如果你也只是想调整首页首屏展示，先从这个文件入手就够了。
AstroPaper 的文章写作规范也很清晰：文章标题写在 frontmatter 的 title 中，正文里的标题从 ## 开始；如果需要文章目录，就在正文中添加 ## Table of contents；图片推荐放在 src/assets 目录下，再用 @/assets/... 的方式在 Markdown 中引用。
后续写文章
在这个项目里，我把文章放在：
src/content/posts/比如这篇文章的位置是：
src/content/posts/coding/_2026-05/astropaper-cloudflare-pages-blog-tutorial.md目录名前面加 _ 的好处是，它只用于本地内容分类，不会出现在最终文章 URL 中。也就是说，这篇文章的地址会更接近：
/posts/coding/astropaper-cloudflare-pages-blog-tutorial/一篇文章的基础 frontmatter 可以这样写：
---
title: 文章标题
description: 文章摘要，会用于列表页和 SEO
pubDatetime: 2026-05-24T09:23:24.373Z
featured: false
draft: false
tags:
- astro
- blog
---写完文章后正常提交并推送：
git add .
git commit -m "docs: add AstroPaper Cloudflare Pages blog tutorial"
git pushCloudflare Pages 会自动触发新一轮部署。构建成功后，线上博客就会更新。