从零开始：用 Astro + Cloudflare Pages 在 5 分钟内部署一个全球可访问的静态网站

本文是我在 2026 年 5 月搭建 cf-pages-guide.pages.dev 的完整过程记录，包含所有命令、项目结构说明和实际截图，任何人都可以按步骤复现。

背景：为什么选 Cloudflare Pages

作为一个写了 10 年代码的全栈工程师，我试过 GitHub Pages、Vercel、Netlify、自建 Nginx……每个平台都有它的适用场景。但最近几年我的个人项目和副业站点基本都迁到了 Cloudflare Pages，原因很简单：

免费套餐无带宽上限：Vercel/Netlify 超量后开始计费，Cloudflare 不限带宽
全球 300+ 边缘节点：国内、海外访问都快，不用额外配 CDN
wrangler CLI 一条命令部署：不需要在控制台点来点去
Pages Functions：静态站也能跑边缘函数，用来做 API 代理、鉴权等

最终效果

部署完成后，你将得到一个 *.pages.dev 的公开地址，效果如下：

网站首屏效果

功能特性区

技术栈

层次	工具	说明
框架	Astro	零 JS 默认输出，构建极快
部署	Cloudflare Pages	全球边缘 CDN，免费无限带宽
CLI	Wrangler	Cloudflare 官方 CLI，一条命令部署
语言	TypeScript	Astro 原生支持

项目结构详解

cf-pages-guide/
├── src/
│   ├── pages/                  ← 每个文件自动映射为一个路由
│   │   ├── index.astro         ← 首页  /
│   │   └── blog/               ← 博客目录
│   │       └── deploy-astro-to-cloudflare-pages.md   ← 本文  /blog/deploy-astro-to-cloudflare-pages
│   └── layouts/
│       └── BlogLayout.astro    ← 博客通用布局（导航 + 文章容器）
├── public/                     ← 静态资源，原样复制到 dist/
│   ├── avatar.jpg
│   └── screenshots/            ← 博客截图
├── dist/                       ← npm run build 后生成，这是真正要部署的目录
│   ├── index.html
│   ├── blog/
│   │   └── deploy-astro-to-cloudflare-pages/index.html
│   └── screenshots/
├── astro.config.mjs            ← Astro 配置（output: static）
├── package.json
└── tsconfig.json

关键原则：

src/pages/ 下的 .astro 和 .md 文件自动成为页面，目录结构就是 URL 结构
public/ 下的文件不经过处理，直接出现在 dist/ 根目录
只有 dist/ 这个目录会被部署到 Cloudflare，其他目录都是开发时用的

第一步：创建 Astro 项目

npm create astro@latest cf-pages-guide -- \
  --template minimal \
  --typescript strict \
  --no-git

cd cf-pages-guide
npm install

minimal 模板只包含最基础的结构，适合从头构建：

src/pages/index.astro   ← 唯一的起点

第二步：开发首页

Astro 文件（.astro）分为两部分：

---
// 1. Frontmatter（服务端执行，相当于 Props 和数据准备）
const title = "Hello Cloudflare Pages";
const features = [
  { icon: "⚡", title: "全球边缘", desc: "300+ 城市节点" },
  // ...
];
---

<!-- 2. HTML 模板（可直接用 JS 表达式） -->
<html>
  <body>
    <h1>{title}</h1>
    {features.map(f => <div>{f.icon} {f.title}</div>)}
  </body>
</html>

Astro 默认是 零 JavaScript 输出——构建时把所有逻辑执行完，生成纯 HTML/CSS，加载极快。

第三步：构建项目

npm run build

输出在 dist/ 目录。构建日志如下：

17:46:20 [build] Building static entrypoints...
17:46:20 [vite] ✓ built in 305ms
17:46:20 [build] 1 page(s) built in 426ms
17:46:20 [build] Complete!

整个构建不到 0.5 秒，这是 Astro 静态模式的优势。

第四步：Cloudflare 控制台准备

打开 Cloudflare Dashboard，进入 Workers 和 Pages 页面：

Workers 和 Pages 控制台

右上角点击 创建应用程序，选择 Upload your static files：

创建应用程序选项

上传静态文件界面

不过，我们不用手动上传——用 Wrangler CLI 更高效。

第五步：用 Wrangler CLI 部署

5.1 确认登录状态

wrangler whoami

输出应该包含你的账号邮箱和账户 ID：

👋 You are logged in with an OAuth Token, associated with the email dustycjh@gmail.com.
┌──────────────────────────────┬──────────────────────────────────┐
│ Account Name                 │ Account ID                       │
├──────────────────────────────┼──────────────────────────────────┤
│ Dustycjh@gmail.com's Account │ aeffd5ca7fb3ce954a6ea953f64629c0 │
└──────────────────────────────┴──────────────────────────────────┘

如果没有登录，先执行：

wrangler login

5.2 创建 Pages 项目（首次）

wrangler pages project create cf-pages-guide --production-branch main

这会在你的 Cloudflare 账户下注册一个新项目，输出：

✨ Successfully created the 'cf-pages-guide' project.
It will be available at https://cf-pages-guide.pages.dev/ once you create your first deployment.

项目名决定了子域名：cf-pages-guide → cf-pages-guide.pages.dev

5.3 部署

wrangler pages deploy dist --project-name cf-pages-guide --branch main

终端输出：

Uploading... (0/5)
Uploading... (2/5)
Uploading... (5/5)
✨ Success! Uploaded 5 files (4.12 sec)

🌎 Deploying...
✨ Deployment complete! Take a peek over at https://4e6ce60e.cf-pages-guide.pages.dev

这里有两个 URL：

https://4e6ce60e.cf-pages-guide.pages.dev — 本次部署的快照地址（每次部署唯一）
https://cf-pages-guide.pages.dev — 生产域名（始终指向最新 main 分支部署）

第六步：验证线上效果

访问 https://cf-pages-guide.pages.dev，完整站点效果：

定价方案区

关于作者区

后续更新流程

每次修改内容后，只需 3 条命令：

# 1. 修改 src/ 下的 .astro 或 .md 文件

# 2. 重新构建
npm run build

# 3. 一键部署
wrangler pages deploy dist --project-name cf-pages-guide --branch main

添加新博客文章

在 src/pages/blog/ 下新建一个 .md 文件即可：

touch src/pages/blog/my-new-post.md

文件顶部加 frontmatter：

---
title: "文章标题"
date: 2026-06-01
author: 陈嘉豪
layout: ../../layouts/BlogLayout.astro
---

正文内容...

Astro 会自动把它编译为 /blog/my-new-post 路由。

常见问题

Q：项目名能改吗？

项目一旦创建，名字不能在控制台改。如果要换名字，需要删掉旧项目重新 project create，域名也会相应变化。

Q：怎么绑定自己的域名？

在 Cloudflare Pages 控制台 → 项目设置 → Custom Domains，填入你的域名，前提是该域名也在 Cloudflare 管理（NS 已迁移）。证书自动签发，几分钟生效。

Q：静态站需要 @astrojs/cloudflare adapter 吗？

不需要。output: 'static'（默认）直接输出纯 HTML/CSS/JS，没有服务端逻辑，不需要任何 adapter。只有开启 SSR（output: 'server'）时才需要 @astrojs/cloudflare。

Q：dist/ 目录要提交到 Git 吗？

不需要，也不建议。把 dist/ 加入 .gitignore，每次本地构建后用 wrangler 部署即可。

总结

整个流程从零到上线：

步骤	耗时
创建 Astro 项目	~30 秒
开发首页内容	~20 分钟
`npm run build`	~0.5 秒
`wrangler project create`	~5 秒
`wrangler pages deploy`	~10 秒
合计	< 25 分钟

Cloudflare Pages 的核心优势在于：把”构建、托管、CDN、SSL、域名绑定”这五件事合并成一套工具，而且免费套餐对个人项目几乎没有限制。作为独立开发者，这是目前性价比最高的静态站托管方案。

作者：陈嘉豪 · 上海 · 2026 年 5 月 本站源码托管在 Cloudflare Pages，所有部署操作均通过 wrangler CLI 完成。