Cloudflare 部署完整教程｜一键部署

在现代 Web 开发中，如何快速、稳定、低成本地部署一个网站或服务，是很多开发者、站长和团队都非常关心的问题。传统部署方式通常需要购买服务器、配置 Nginx、安装运行环境、设置 SSL 证书、处理安全策略和运维监控，对于新手来说门槛较高。

而 Cloudflare 提供了一套非常友好的云端部署方案，包括 Cloudflare Pages、Cloudflare Workers、Workers KV、D1 数据库、R2 对象存储 等服务。借助这些产品，我们可以非常快速地部署静态网站、前端项目、API 服务、Serverless 应用，甚至构建完整的全栈项目。

本文将以中文完整介绍 Cloudflare 的部署流程，重点讲解如何通过 Cloudflare 实现“一键部署”，适合新手入门，也适合有一定开发经验的用户作为参考。

一、Cloudflare 是什么？

Cloudflare 最早以 CDN 和网站安全服务闻名，它可以为网站提供全球加速、防御 DDoS 攻击、SSL 证书、DNS 托管等能力。随着云计算和 Serverless 技术的发展，Cloudflare 逐渐推出了更多面向开发者的产品。

常见的 Cloudflare 开发者服务包括：

对于普通用户来说，最常用的是 Cloudflare Pages 和 Cloudflare Workers。前者适合部署网站，后者适合部署接口和轻量服务。

二、为什么选择 Cloudflare 部署？

相比传统服务器部署，Cloudflare 有以下几个明显优势。

1. 免费额度充足

Cloudflare Pages 和 Workers 都提供了较为宽松的免费额度。对于个人博客、小型项目、开源项目、演示站点来说，免费额度通常已经足够使用。

2. 全球 CDN 加速

Cloudflare 拥有覆盖全球的边缘节点。部署到 Cloudflare 后，用户访问时会自动从距离较近的节点获取内容，从而提升访问速度。

3. 自动 HTTPS

传统部署中，配置 SSL 证书可能需要手动申请、续期和配置。而 Cloudflare 会自动为 Pages 项目提供 HTTPS，绑定自定义域名后也可以快速启用 SSL。

4. 无需维护服务器

Cloudflare Pages 和 Workers 都是 Serverless 模式，不需要你关心服务器系统、安全补丁、服务进程、端口转发等问题。

5. 支持 Git 自动部署

你可以将项目托管在 GitHub 或 GitLab 上，Cloudflare Pages 可以直接连接仓库。当你提交代码后，Cloudflare 会自动构建并部署新版本。

6. 适合一键部署

很多项目可以通过模板或仓库快速导入 Cloudflare，实现近似“一键部署”的体验。对于开源项目来说，这种方式非常方便。

三、部署前准备工作

在正式部署之前，你需要准备以下内容。

1. 注册 Cloudflare 账号

访问 Cloudflare 官网：

https://www.cloudflare.com/

点击注册，使用邮箱创建账号即可。

注册完成后，建议完成邮箱验证，否则部分功能可能无法正常使用。

2. 准备 GitHub 账号

如果你希望通过 Cloudflare Pages 自动部署项目，建议准备一个 GitHub 账号。

GitHub 官网：

https://github.com/

将你的项目上传到 GitHub 后，Cloudflare 可以读取仓库代码并自动部署。

3. 准备一个项目

你可以部署以下类型项目：

• HTML/CSS/JavaScript 静态网页；
• Vue 项目；
• React 项目；
• Next.js 静态导出项目；
• Vite 项目；
• Astro 项目；
• Hugo、Hexo、Jekyll 博客；
• Workers API 服务；
• 简单的反向代理、接口服务或边缘函数。

如果你只是想测试，也可以先准备一个最简单的 index.html 文件。

示例：

  
  


  
Hello Cloudflare Pages!
  
这是我的第一个 Cloudflare 部署项目。

四、方式一：使用 Cloudflare Pages 一键部署静态网站

Cloudflare Pages 是最适合新手使用的部署方式。如果你的项目是前端网站或静态页面，推荐优先选择 Pages。

第一步：登录 Cloudflare 控制台

打开 Cloudflare 控制台：

https://dash.cloudflare.com/

登录账号后，在左侧菜单中找到：

Workers 和 Pages

然后点击进入。

第二步：创建 Pages 项目

在页面中选择：

创建应用程序

然后选择：

Pages

接着点击：

连接到 Git

Cloudflare 会提示你授权 GitHub 或 GitLab。这里以 GitHub 为例。

第三步：授权 GitHub 仓库

点击 GitHub 授权后，你需要选择 Cloudflare 可以访问的仓库。

通常有两种授权方式：

1. 授权所有仓库；
2. 只授权指定仓库。

为了安全，建议只授权需要部署的项目仓库。

授权完成后，Cloudflare 会列出你可以部署的仓库。选择对应项目，然后点击开始设置。

第四步：配置构建参数

Cloudflare Pages 会要求填写项目名称、分支、构建命令和输出目录。

不同项目类型配置不同。

1. 普通静态 HTML 项目

如果你的项目只有 index.html、style.css、script.js 等静态文件，通常可以这样配置：

构建命令：留空
输出目录：/

如果你的文件在 public 目录下，则输出目录填写：

public

2. Vite 项目

如果是 Vite 项目，通常配置如下：

构建命令：npm run build
输出目录：dist

3. Vue 项目

Vue CLI 项目通常配置如下：

构建命令：npm run build
输出目录：dist

4. React 项目

Create React App 项目通常配置如下：

构建命令：npm run build
输出目录：build

如果是 Vite + React，则一般是：

构建命令：npm run build
输出目录：dist

5. Astro 项目

Astro 项目通常配置如下：

构建命令：npm run build
输出目录：dist

6. Hugo 项目

Hugo 项目通常配置如下：

构建命令：hugo
输出目录：public

注意：如果使用 Hugo，需要在环境变量中指定 Hugo 版本，或者在项目配置中确保构建环境支持。

第五步：点击部署

确认配置无误后，点击：

保存并部署

Cloudflare 会自动拉取 GitHub 仓库代码，然后执行构建命令。构建完成后，会将输出目录中的文件发布到 Cloudflare Pages。

如果部署成功，你会获得一个默认域名，格式类似：

https://your-project.pages.dev

打开这个链接，就可以访问你的项目了。

五、Pages 一键部署按钮的实现方式

很多开源项目会提供类似“Deploy to Cloudflare”的按钮。用户点击按钮后，可以直接跳转到 Cloudflare 的部署页面，从而快速完成部署。

通常可以在项目 README 中加入如下按钮：

[![Deploy to Cloudflare Pages](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/)

不过需要注意，Cloudflare 的一键部署链接与具体项目结构、仓库地址和平台支持有关。对于不同项目，可能需要用户先 Fork 仓库，再连接到 Cloudflare Pages。

一个常见的“一键部署”流程是：

1. 用户点击 GitHub 仓库中的 Fork 按钮；
2. 将项目复制到自己的 GitHub 账号下；
3. 点击 Cloudflare Pages 创建项目；
4. 选择刚刚 Fork 的仓库；
5. 按照说明填写构建命令和输出目录；
6. 点击部署。

为了让用户体验更接近“一键部署”，你可以在 README 中清晰写出项目部署参数，例如：

## Cloudflare Pages 部署

构建命令：

```bash
npm run build

输出目录：

dist

Node.js 版本：

20

这样用户不需要猜测配置，部署成功率会更高。

---

## 六、方式二：使用 Cloudflare Workers 部署 API 服务

如果你要部署的不是静态网站，而是一个接口服务、边缘函数、代理逻辑或 Serverless 应用，就可以使用 Cloudflare Workers。

Workers 的核心特点是：代码运行在 Cloudflare 的边缘节点上，请求到达后由 Worker 脚本处理并返回响应。

---

### 第一步：安装 Node.js

本地部署 Workers 通常需要安装 Node.js。

访问官网下载安装：

```text
https://nodejs.org/

建议使用 Node.js 18 或 Node.js 20 以上版本。

安装完成后，在终端执行：

node -v
npm -v

如果能看到版本号，说明安装成功。

第二步：安装 Wrangler

Wrangler 是 Cloudflare Workers 的官方命令行工具。

安装命令：

npm install -g wrangler

安装完成后检查版本：

wrangler -v

第三步：登录 Cloudflare

在终端执行：

wrangler login

浏览器会打开 Cloudflare 授权页面，点击授权即可。

授权成功后，Wrangler 就可以帮助你创建、预览和部署 Workers 项目。

第四步：创建 Workers 项目

执行命令：

npm create cloudflare@latest my-worker

根据提示选择项目类型。

如果你只是想创建一个简单 Worker，可以选择基础 Worker 模板。

进入项目目录：

cd my-worker

项目中通常会有 src/index.js 或 src/index.ts 文件。

一个最简单的 Worker 示例：

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello Cloudflare Workers!");
  },
};

第五步：本地预览

执行：

npm run dev

或：

wrangler dev

终端会显示本地预览地址，例如：

http://localhost:8787

打开后可以看到 Worker 返回的内容。

第六步：部署 Workers

确认没有问题后，执行：

npm run deploy

或：

wrangler deploy

部署成功后，终端会返回一个 Workers 地址，通常类似：

https://my-worker.your-subdomain.workers.dev

访问该地址即可看到部署结果。

七、绑定自定义域名

无论是 Cloudflare Pages 还是 Workers，你都可以绑定自己的域名。

1. 将域名接入 Cloudflare

如果你的域名还没有接入 Cloudflare，需要先添加站点。

步骤如下：

1. 登录 Cloudflare 控制台；
2. 点击“添加站点”；
3. 输入你的域名；
4. 选择套餐，个人项目可以选择免费套餐；
5. Cloudflare 会扫描现有 DNS 记录；
6. 按照提示到域名注册商处修改 NS 服务器；
7. 等待 DNS 生效。

NS 生效时间通常从几分钟到数小时不等，极少数情况可能需要 24 小时以上。

2. Pages 绑定自定义域名

进入 Cloudflare Pages 项目，找到：

自定义域

点击添加自定义域名，例如：

www.example.com

Cloudflare 会自动提示你添加 DNS 记录。通常情况下，如果域名已经托管在 Cloudflare，会自动完成配置。

配置完成后，等待证书签发，即可通过自定义域名访问。

3. Workers 绑定自定义域名

进入 Worker 项目，找到：

触发器

然后添加路由或自定义域。

例如你希望让 Worker 处理：

api.example.com

可以将该子域名绑定到 Worker。

也可以配置路由，例如：

example.com/api/*

这样访问 /api/ 开头的请求时，会交给 Worker 处理。

八、环境变量配置

很多项目需要配置环境变量，例如 API Key、数据库地址、站点名称等。

1. Pages 环境变量

进入 Pages 项目设置，找到：

设置 -> 环境变量

你可以分别配置：

• 生产环境变量；
• 预览环境变量。

例如：

SITE_NAME=My Cloudflare Site
API_BASE_URL=https://api.example.com

如果是前端项目，需要注意变量命名规则。例如 Vite 项目中，暴露到前端的变量通常需要以 VITE_ 开头：

VITE_API_BASE_URL=https://api.example.com

2. Workers 环境变量

Workers 可以在 wrangler.toml 中配置普通变量：

name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

[vars]
SITE_NAME = "My Worker"

如果是敏感信息，例如密钥、Token、数据库密码，不建议直接写入配置文件，应使用 secret：

wrangler secret put API_TOKEN

输入值后，Cloudflare 会将其安全保存。

在 Worker 中读取：

export default {
  async fetch(request, env, ctx) {
    return new Response(env.API_TOKEN);
  },
};

实际项目中，不建议直接返回密钥，这里只是演示读取方式。

九、常见项目部署配置示例

下面列出几类常见项目的 Cloudflare Pages 部署配置。

1. VitePress 文档站点

构建命令：npm run docs:build
输出目录：docs/.vitepress/dist

如果你的 VitePress 项目结构不同，请以实际输出目录为准。

2. Hexo 博客

构建命令：npm run build
输出目录：public

或者：

构建命令：hexo generate
输出目录：public

3. Next.js 项目

如果是纯静态导出，可以配置：

构建命令：npm run build
输出目录：out

同时需要在 next.config.js 中开启静态导出：

const nextConfig = {
  output: "export",
};

module.exports = nextConfig;

如果你的 Next.js 项目需要服务端渲染，则需要使用适配 Cloudflare 的方案，例如 @cloudflare/next-on-pages，配置会更复杂一些。

4. Nuxt 项目

如果是静态生成：

构建命令：npm run generate
输出目录：dist

如果是 SSR 项目，则需要根据 Nuxt 的 Cloudflare 部署适配方式进行配置。

5. Astro 博客

构建命令：npm run build
输出目录：dist

Astro 非常适合部署到 Cloudflare Pages，构建速度快，静态输出清晰。

十、部署失败的常见原因与解决方法

Cloudflare 部署虽然简单，但新手在第一次部署时仍然可能遇到问题。下面列出常见错误。

1. 构建命令错误

如果你的项目没有 build 脚本，却填写了：

npm run build

就会部署失败。

解决方法：检查 package.json 中是否存在：

{
  "scripts": {
    "build": "vite build"
  }
}

如果没有，需要添加正确的构建脚本。

2. 输出目录填写错误

很多项目部署失败不是构建失败，而是构建成功后找不到输出文件。

例如 Vite 项目输出目录通常是：

dist

React CRA 输出目录通常是：

build

Hugo、Hexo 通常是：

public

请根据实际项目填写。

3. Node.js 版本不兼容

部分项目需要较新的 Node.js 版本。如果 Cloudflare 默认版本过旧，可能导致构建失败。

解决方法：在 Pages 环境变量中添加：

NODE_VERSION=20

也可以根据项目需要设置为：

NODE_VERSION=18

4. 依赖安装失败

如果依赖安装失败，可能是包管理器不一致导致的。

常见包管理器包括：

• npm；
• pnpm；
• yarn。

如果项目使用 pnpm，建议在构建命令中明确写：

pnpm install && pnpm build

或者确保仓库中存在 pnpm-lock.yaml。

5. 环境变量缺失

如果项目依赖环境变量，而 Cloudflare 中没有配置，就可能构建失败或运行异常。

解决方法：检查项目文档，补充必要变量。

例如：

VITE_API_URL=https://api.example.com
DATABASE_URL=xxxx

6. 路由刷新 404

单页应用如 Vue、React 在使用前端路由时，直接刷新 /about 页面可能出现 404。

解决方法：在输出目录中添加 _redirects 文件，内容如下：

/* /index.html 200

这样所有路径都会回退到 index.html，由前端路由接管。

十一、Cloudflare Pages 与 Workers 如何选择？

很多人不知道 Pages 和 Workers 应该选哪个。可以简单理解为：

• Pages：适合网站、博客、文档、前端项目；
• Workers：适合 API、函数、代理、边缘计算逻辑；
• Pages Functions：适合在 Pages 项目中增加少量后端接口。

如果你的项目是一个纯静态站点，选 Pages 即可。

如果你的项目需要处理请求逻辑，例如：

• 根据请求路径返回不同数据；
• 调用第三方接口；
• 鉴权；
• 返回 JSON；
• 做边缘缓存；
• 简单代理；

那么 Workers 更合适。

如果你的网站主要是静态页面，但又需要几个 API 接口，可以使用 Pages Functions。

十二、使用 Pages Functions 添加接口

Cloudflare Pages 不仅能部署静态网站，还可以通过 Functions 增加 Serverless 接口。

例如在项目根目录创建：

functions/api/hello.js

内容如下：

export async function onRequest(context) {
  return new Response(
    JSON.stringify({
      message: "Hello from Cloudflare Pages Functions!",
    }),
    {
      headers: {
        "Content-Type": "application/json",
      },
    }
  );
}

部署后访问：

https://your-project.pages.dev/api/hello

即可看到接口返回结果。

这种方式适合轻量级接口，不需要单独创建 Worker 项目。

十三、安全建议

部署项目时，除了能跑起来，也要注意安全。

1. 不要暴露敏感密钥

不要将 API Token、数据库密码、私钥写在前端代码中。前端项目中的环境变量如果被打包到浏览器，就可能被任何人看到。

2. 使用 Cloudflare Secret 保存敏感信息

Workers 项目应使用：

wrangler secret put SECRET_NAME

Pages Functions 中也应通过 Cloudflare 控制台设置环境变量。

3. 配置访问限制

如果是后台管理页面，可以考虑使用 Cloudflare Zero Trust、Access 或基础鉴权进行保护。

4. 开启缓存策略

对于静态资源，可以合理设置缓存，提高访问速度并减少构建压力。

5. 注意跨域配置

如果你的 API 提供给前端调用，需要正确配置 CORS，但不要随意开放所有来源，尤其是涉及用户数据时。

十四、推荐的一键部署项目结构

为了让别人更容易部署你的项目，建议保持清晰的项目结构。

例如：

my-project
├── public
├── src
├── package.json
├── package-lock.json
├── README.md
└── wrangler.toml

README 中应写清楚：

# 项目名称

## 部署到 Cloudflare Pages

构建命令：

```bash
npm run build

输出目录：

dist

环境变量：

VITE_API_URL=

本地运行

npm install
npm run dev

如果项目使用 Workers，应写清楚：

```bash
npm install
wrangler login
wrangler deploy

这样用户拿到项目后，可以快速完成部署。

十五、完整部署流程总结

如果你想用 Cloudflare 一键部署一个网站，可以按照下面流程操作：

1. 注册并登录 Cloudflare；
2. 准备 GitHub 仓库；
3. 将项目代码推送到 GitHub；
4. 进入 Cloudflare 控制台；
5. 打开 Workers 和 Pages；
6. 创建 Pages 项目；
7. 连接 GitHub 仓库；
8. 填写构建命令和输出目录；
9. 设置 Node.js 版本和环境变量；
10. 点击保存并部署；
11. 等待构建完成；
12. 访问 pages.dev 默认域名；
13. 如有需要，绑定自定义域名；
14. 配置 HTTPS、缓存和重定向；
15. 后续通过 Git 提交实现自动更新。

十六、结语

Cloudflare 部署最大的优势在于简单、快速、稳定，并且免费额度对个人用户非常友好。对于静态网站、博客、文档站点和前端项目来说，Cloudflare Pages 几乎是目前最方便的部署方案之一；对于 API、代理和边缘计算任务，Cloudflare Workers 则提供了强大的 Serverless 能力。

如果你是新手，建议先从 Cloudflare Pages 部署一个最简单的静态网站开始，熟悉构建命令、输出目录、环境变量和自定义域名配置。等掌握基本流程后，再尝试 Workers、KV、D1、R2 等更高级的功能。

只要项目结构清晰、构建参数正确，Cloudflare 可以让你真正实现接近“一键部署”的体验。后续更新也非常方便：只需要将代码提交到 GitHub，Cloudflare 就会自动完成构建和发布，让你把更多时间放在开发内容本身，而不是服务器运维上。