从零搭建 Astro 博客并部署到 Cloudflare Pages

TL;DR

用 Astro 框架搭建一个个人博客，部署到 Cloudflare Pages，全程免费。你需要一台能上网电脑，不需要任何前端开发经验。读完本文，你将拥有一个线上可访问个人博客。

你将得到什么

完成本文所有步骤后，你会得到：

一个基于 Astro 的静态博客站点
一篇在线可见文章
一个绑定到你域名 HTTPS 地址
每次 push 代码自动部署 CI 流程

费用：0 元。Cloudflare Pages 免费额度对个人博客绑绑有余。

前置准备

只需要两样东西：

一台电脑（Windows / macOS / Linux 都行）
一个代码仓库账号（GitHub 或 Gitee，免费注册）

不需要购买服务器，不需要备案域名。Cloudflare Pages 提供免费 *.pages.dev 子域名，开箱即用。

第一步：安装 Node.js

Astro 基于 Node.js 运行。先确认你有没有装过：

node -v

如果输出类似 v20.x.x 或 v22.x.x，跳过这步。如果提示”命令未找到”，去 Node.js 官网下载 LTS 版本安装。

安装完后再跑一次 node -v，看到版本号就说明成功了。

版本要求：Astro 需要 Node.js 18.14.1 以上。建议直接装 LTS（长期支持版），省心。

第二步：创建 Astro 项目

打开终端（Windows 用 PowerShell，macOS 用 Terminal），进入你想放项目目录，执行：

npm create astro@latest

Astro 会问你几个问题，这样选：

问题	选择	原因
Where should we create your new project?	`my-blog`	项目文件夹名
How would you like to start your new project?	`Use blog template`	自带博客结构，省力
Install dependencies?	`Yes`	自动装依赖
Do you plan to write TypeScript?	`No`	零基础先不碰 TS
Initialize a new git repository?	`Yes`	后面部署需要 git

等它跑完，你的博客项目就创建好了。进入目录看看结构：

cd my-blog
npm run dev

浏览器打开 http://localhost:4321，你应该能看到一个默认博客页面。

按 Ctrl + C 停止预览。

第三步：认识项目结构

Astro 博客模板核心文件不多：

my-blog/
├── src/
│   ├── content/
│   │   └── blog/        ← 文章放在这里
│   │       ├── first-post.md
│   │       └── second-post.md
│   ├── layouts/
│   │   └── BlogPost.astro  ← 文章页面模板
│   └── pages/
│       └── blog/
│           └── [...slug].astro  ← 文章路由
├── public/              ← 静态资源（图片等）
├── astro.config.mjs     ← 框架配置
└── package.json

你现在只需要关注两个地方：

src/content/blog/ — 往这里放文章
astro.config.mjs — 站点基本信息

第四步：写第一篇文章

在 src/content/blog/ 下新建一个 Markdown 文件，比如 hello-world.md：

---
title: '我的第一篇博客'
description: '用 Astro 搭建博客后写的第一篇文章'
pubDate: 2026-05-20
category: '随笔'
tags: ['开始']
---

Hello, world!

这是我用 Astro 搭建的博客。从今天起，我有了一个属于自己的写作空间。

## 为什么自建博客

平台写作方便，但你的内容不完全属于你。自建博客让你掌控一切：排版、域名、内容归属。

## 下一步

接下来我会调整站点样式、添加评论功能、绑定自定义域名。一步一步来。

文件顶部 --- 之间的部分叫 frontmatter，是文章元数据：

字段	含义	必填
`title`	文章标题	是
`description`	文章描述，用于 SEO	是
`pubDate`	发布日期	是
`category`	分类	否
`tags`	标签数组	否

保存后运行 npm run dev，访问 http://localhost:4321/blog/hello-world 就能看到新文章了。

第五步：修改站点信息

打开 astro.config.mjs，找到 site 字段，改成你域名：

export default defineConfig({
  site: 'https://your-site.pages.dev',
  // ...
});

如果暂时没有域名，先填 Cloudflare Pages 分配的 *.pages.dev 地址，后面再改。

第六步：推送代码到 Git 仓库

Cloudflare Pages 通过监听 Git 仓库的 push 事件自动部署。先把代码推上去：

# 如果创建项目时没有初始化 git
git init
git add .
git commit -m "init: Astro blog"

# 在 GitHub 或 Gitee 上创建一个名为 my-blog 的空仓库，然后：
git remote add origin https://github.com/你的用户名/my-blog.git
git push -u origin main

Gitee 还是 GitHub？ 都行。国内访问 Gitee 更快，但 Cloudflare Pages 原生支持 GitHub。如果你用 Gitee，后面需要在 Cloudflare 里配置 Gitee 的 webhook。

第七步：部署到 Cloudflare Pages

注册 Cloudflare 账号（免费）
进入 Pages 控制台，点击 Create a project
选择 Connect to Git
授权并选择你刚才创建 my-blog 仓库
配置构建设置：

设置项	值
Framework preset	`Astro`
Build command	`npm run build`
Build output directory	`dist`

点击 Save and Deploy

等一两分钟，Cloudflare 会完成第一次构建和部署。成功后你会得到一个 https://my-blog.pages.dev 的地址，打开就能看到你博客了。

第八步：绑定自定义域名（可选）

如果你有自己域名：

在 Cloudflare Pages 项目设置里，点击 Custom domains
添加你域名，比如 blog.yourdomain.com
Cloudflare 会给你一条 CNAME 记录，去你的域名 DNS 管理处添加
等 DNS 生效（通常钟到几小时）

之后访问 blog.yourdomain.com 就是你博客了，自动 HTTPS。

日常写作流程

以后写新文章只需三步：

# 1. 在 src/content/blog/ 下新建 .md 文件，写好内容

# 2. 本地预览
npm run dev

# 3. 确认没问题，推送部署
git add .
git commit -m "新文章：文章标题"
git push

push 之后 Cloudflare Pages 自动构建部署，通常 1-2 分钟上线。

常见问题

构建失败怎么办？

去 Cloudflare Pages 控制台查看构建日志，90% 的情况是：

npm run build 报错 → 本地先跑一次确认能构建
依赖版本不兼容 → 删掉 node_modules 重新 npm install

怎么修改博客样式？

Astro 的组件都在 src/ 下，.astro 文件里 <style> 标签内写 CSS。改完本地 npm run dev 预览，满意了再 push。

怎么添加 RSS 订阅？

npm install @astrojs/rss

然后在 src/pages/rss.xml.js 中配置。Astro 官方文档有详细说明。

写在

自建博客核心收益对内容掌控。你写的每一篇文章、做的每一次样式调整，都属于你自己。平台随时可以改规则，你的博客不会。

这套方案成本是零，但你需要花时间调整样式和补充内容。别急，一篇一篇写，一个一个改。博客是长期事。

延伸阅读

种下你的想法

在花园里留下一条评论，和这篇文章一起生长。

COMMENTS