Aug 27, 2026

从零开始：Astro + Cloudflare Pages 手把手搭建个人技术博客

如果你只是想拥有一个属于自己的技术博客，其实不一定需要购买云服务器，也不需要维护 Nginx、数据库和 Docker。

这篇文章记录的是我实际搭建个人博客的完整过程：

Astro + GitHub + Cloudflare Pages + 独立域名

最终的工作流非常简单：

本地写 Markdown
    ↓
git push
    ↓
GitHub
    ↓
Cloudflare Pages 自动构建
    ↓
个人博客自动更新

这种方式特别适合技术博客：成本低、维护简单、访问速度不错，而且所有文章都以 Markdown 文件保存在自己的 Git 仓库里。

下面从零开始完整走一遍。

一、为什么选择 Astro + Cloudflare Pages

最开始我考虑过 Halo、WordPress 等传统博客系统，但如果使用这些系统，通常需要一台可以被公网访问的服务器。

我的服务器属于公司内网服务器，外部无法直接访问，而且公司服务器也不适合承载个人网站。

于是最终选择了静态博客方案：

Astro：负责生成博客页面；
GitHub：保存博客源码和文章；
Cloudflare Pages：负责构建和托管网站；
独立域名：作为网站最终访问地址。

这样最大的好处是：

不需要单独购买服务器；
不需要维护数据库；
不需要配置 Nginx；
不需要自己申请 HTTPS 证书；
每次 git push 后网站自动更新；
博客源码和文章都掌握在自己手里。

二、准备环境

我的本地环境是 Windows。

需要准备：

Node.js
npm
Git
GitHub 账号
Cloudflare 账号
VS Code（推荐）
一个域名（可以最后再买）

先检查本机环境：

node -v
npm -v
git --version

我当时使用的是：

Node.js v24.14.0
Windows x64

Astro 建议使用较新的 Node.js 偶数版本。如果是新安装环境，我更建议直接使用 Node.js 22 LTS 或当前受支持的 LTS 版本。

三、创建 Astro 博客

找一个自己存放代码的目录，例如：

D:
cd D:\codes\blog

创建 Astro 官方 Blog 模板：

npm create astro@latest -- --template blog

项目名称例如：

xinghai-blog

安装过程中按照提示：

Install dependencies? → Yes
Initialize a git repository? → Yes

创建完成后：

cd xinghai-blog
npm run dev

正常情况下会看到：

Local http://localhost:4321/

浏览器打开：

http://localhost:4321

这时应该可以看到 Astro 默认博客首页。

四、第一个坑：`astro` 不是内部或外部命令

我第一次执行：

npm run dev

遇到：

'astro' 不是内部或外部命令，也不是可运行的程序
或批处理文件。

这个问题通常说明项目依赖没有正确安装。

先检查：

Test-Path .\node_modules
Test-Path .\node_modules\.bin\astro.cmd

如果第二个结果是：

False

直接重新安装依赖：

npm install

然后再次启动：

npm run dev

这里不建议通过：

npm install -g astro

全局安装 Astro。

Astro 应该作为当前项目的本地依赖使用，否则本地版本、CI 构建版本和 Cloudflare 构建版本可能不一致。

五、第二个坑：Cannot find native binding

重新安装依赖后，我又遇到了第二个问题：

Cannot find native binding.

npm has a bug related to optional dependencies.
Please try npm i again after removing both
package-lock.json and node_modules directory.

后面还有：

astro.win32-x64-msvc.node is not a valid Win32 application

这个报错看起来很吓人，但实际问题主要集中在 Astro 的 Windows 原生依赖没有被正确安装。

我先检查了 Node.js 和 Windows 的架构：

node -p "JSON.stringify({version:process.version, arch:process.arch, platform:process.platform, execPath:process.execPath}, null, 2)"

{
  "version": "v24.14.0",
  "arch": "x64",
  "platform": "win32",
  "execPath": "D:\\program\\nodejs\\node.exe"
}

再检查 Windows：

[Environment]::Is64BitOperatingSystem
Get-CimInstance Win32_OperatingSystem | Select-Object OSArchitecture

确认：

True
64 位

因此并不是 32 位和 64 位架构冲突。

最终处理方法是完整删除依赖和锁文件：

Remove-Item -Recurse -Force .\node_modules -ErrorAction SilentlyContinue
Remove-Item -Force .\package-lock.json -ErrorAction SilentlyContinue

npm cache clean --force
npm install --include=optional --registry=https://registry.npmjs.org/

然后：

npm run dev

如果你的公司网络使用 Nexus、Artifactory 或其他 npm 镜像，也建议先检查：

npm config get registry

必要时直接使用官方 npm Registry：

npm config set registry https://registry.npmjs.org/

这个问题很容易被误认为是 Astro 本身有 Bug，但实际上更常见的是 npm 可选依赖、缓存或者镜像源导致原生二进制文件安装异常。

六、修改博客名称

Astro 官方 Blog 模板创建出来后，首先修改：

src/consts.ts

例如：

export const SITE_TITLE = '景川技术手记';

export const SITE_DESCRIPTION =
	'记录云原生、数据平台、AI生产力与科研方法，以及真实环境中的问题、排查与实践。';

这样网站名称、SEO 描述等内容就会使用自己的信息。

七、修改首页

首页文件通常是：

src/pages/index.astro

默认首页是 Astro 官方示例内容。

可以把它改成个人介绍，例如：

<h1>你好，我是景川</h1>

<p>
	记录云原生、数据平台、AI生产力与科研方法，
	也记录那些真正发生在实际环境中的问题、排查与思考。
</p>

<a href="/blog">查看文章</a>
<a href="/about">关于我</a>

顶部菜单通常位于：

src/components/Header.astro

可以把：

Home
Blog
About

改成：

首页
文章
关于

这样第一版中文个人博客就基本成型了。

八、博客文章放在哪里

Astro Blog 模板的文章一般放在：

src/content/blog/

比如创建：

src/content/blog/hello-world.md

内容：

---
title: "我的第一篇博客"
description: "这是我的第一篇 Astro 博客文章。"
pubDate: 2026-08-27
---

这是我的第一篇文章。

以后所有内容都可以直接使用 Markdown 编写。

这也是静态博客最大的优势之一：

文章就是文件。

即使以后不用 Astro 了，这些 Markdown 文件仍然可以很容易迁移到其他博客系统。

九、本地预览和正式构建

开发过程中：

npm run dev

打开：

http://localhost:4321

正式部署之前最好再执行一次：

npm run build

Astro 会生成：

dist/

这个目录就是最终生成的静态网站。

如果：

npm run build

能够正常执行，Cloudflare Pages 通常也就具备了正常构建的基础。

十、创建 GitHub 仓库

xinghai-blog

因为本地 Astro 项目已经初始化 Git，所以 GitHub 新仓库不需要再勾选：

README
.gitignore
License

本地执行：

git add .
git commit -m "Initial Astro blog"
git branch -M main

添加远程仓库：

git remote add origin https://github.com/你的用户名/xinghai-blog.git

例如：

git remote add origin https://github.com/CXAXH/xinghai-blog.git

检查：

git remote -v

然后：

git push -u origin main

十一、第三个坑：GitHub 不再支持密码推送

这里我又遇到了：

remote: Invalid username or token.
Password authentication is not supported for Git operations.

fatal: Authentication failed

原因很简单：

GitHub 的 HTTPS Git 操作已经不能直接使用 GitHub 登录密码。

如果 Windows 中缓存了错误凭据，可以打开：

Windows 凭据管理器
→ Windows 凭据

找到类似：

git:https://github.com
github.com

删除旧凭据。

然后重新执行：

git push -u origin main

如果安装了 Git Credential Manager，通常会自动打开浏览器，让你完成 GitHub 授权。

这是我更推荐的方式。

另外也可以使用 GitHub Personal Access Token，但不要把 Token 提交到代码仓库，也不要写进任何公开配置文件。

十二、部署到 Cloudflare Pages

代码成功推送到 GitHub 后，就可以开始部署。

Workers & Pages

然后创建应用。

这里有一个很容易踩的坑。

十三、第四个坑：不要选错成 Workers 部署

我第一次创建时看到的默认部署命令是：

npx wrangler deploy

如果你也看到这个，说明很可能进入了：

Cloudflare Workers

而不是我们这里使用的：

Cloudflare Pages

对于普通 Astro 静态博客，不需要自己执行：

npx wrangler deploy

应该选择：

Workers & Pages
→ Create
→ Pages
→ Connect to Git

连接 GitHub 后，选择博客仓库。

我的核心配置如下：

Production branch：main
Framework preset：Astro
Build command：npm run build
Build output directory：dist

根目录如果 Astro 项目就在 Git 仓库根目录，可以留空。

部署完成后，Cloudflare 会提供类似：

https://项目名.pages.dev

的地址。

到这里，一个完全不依赖自己服务器的个人博客已经上线了。

十四、绑定自己的域名

如果已经有域名，可以继续在 Cloudflare Pages 项目中进入：

Custom domains

添加自己的域名。

例如：

www.example.com

或者根域名：

example.com

如果域名 DNS 已经托管在 Cloudflare，配置会非常简单。

绑定完成后，还需要修改 Astro 项目中的：

astro.config.mjs

加入或修改：

export default defineConfig({
	site: 'https://www.example.com',
});

这里一定要写最终正式域名。

因为它会影响：

Sitemap
RSS
Canonical URL
SEO
社交分享链接

修改后重新提交：

git add .
git commit -m "Configure custom domain"
git push

Cloudflare Pages 会自动重新部署。

十五、以后怎么发布文章

整个博客搭好以后，日常维护反而非常简单。

例如创建新文章：

src/content/blog/kubernetes-note.md

写完之后本地预览：

npm run dev

确认没有问题：

git add .
git commit -m "新增 Kubernetes 文章"
git push

后面的事情全部由 Cloudflare 自动完成：

git push
    ↓
GitHub 收到新代码
    ↓
Cloudflare Pages 触发构建
    ↓
npm run build
    ↓
生成 dist
    ↓
网站自动更新

不用登录服务器。

不用上传文件。

不用手动重启 Nginx。

十六、我的最终目录结构

搭建完成后，大致结构如下：

xinghai-blog/
│
├─ public/
│  └─ images/
│
├─ src/
│  ├─ components/
│  ├─ content/
│  │  └─ blog/
│  │     ├─ astro-cloudflare-pages-blog-guide.md
│  │     └─ ...
│  │
│  ├─ layouts/
│  ├─ pages/
│  │  ├─ index.astro
│  │  └─ ...
│  │
│  └─ consts.ts
│
├─ astro.config.mjs
├─ package.json
└─ tsconfig.json

其中真正需要经常操作的，主要就是：

src/content/blog/

以后绝大部分时间都只是在这里增加 Markdown 文件。

十七、这套方案适合什么人

我认为这套方案尤其适合：

程序员个人博客；
技术文档站；
个人作品集；
科研技术笔记；
AI 工具实践博客；
不想维护服务器的人；
想拥有自己域名和内容资产的人。

如果你的站点以后需要：

用户注册；
评论后台；
会员系统；
付费内容；
数据库；
复杂管理后台；

那么可以再考虑 Halo、WordPress 或动态 Web 应用。

但对于一个以文章为核心的个人技术博客：

Astro + GitHub + Cloudflare Pages 已经足够好用。

十八、完整命令速查

最后把最核心的命令整理一下。

创建项目：

npm create astro@latest -- --template blog

启动：

npm run dev

构建：

npm run build

如果 Astro 原生依赖异常：

Remove-Item -Recurse -Force .\node_modules -ErrorAction SilentlyContinue
Remove-Item -Force .\package-lock.json -ErrorAction SilentlyContinue

npm cache clean --force
npm install --include=optional --registry=https://registry.npmjs.org/

提交 Git：

git add .
git commit -m "更新博客"
git push

Cloudflare Pages：

Framework preset：Astro
Build command：npm run build
Build output directory：dist
Production branch：main

以后每次更新博客，真正需要做的其实只有：

git add .
git commit -m "新增文章"
git push

写在最后

以前搭个人博客，常见的流程是：

买服务器
→ 安装 Linux
→ 配置 Nginx
→ 配置 HTTPS
→ 安装数据库
→ 安装博客程序
→ 定期备份
→ 定期升级
→ 处理安全问题

而现在，如果核心需求只是写文章，可以把基础设施大幅简化：

Markdown
→ GitHub
→ Cloudflare Pages

工具变简单以后，真正应该花时间的事情也就更加明确了：

不是继续折腾博客系统，而是开始认真写内容。

这也是我最终选择 Astro + Cloudflare Pages 的原因。