Cloudflare 部署完整教程｜附配置文件

Cloudflare 是目前非常流行的全球化网络服务平台，除了我们熟悉的 DNS 解析、CDN 加速、HTTPS 证书、防火墙防护 之外，它还提供了非常适合个人开发者和中小团队使用的部署能力，例如：

• Cloudflare Pages：适合部署静态网站、前端项目、文档站、博客等；
• Cloudflare Workers：适合部署 Serverless API、边缘函数、代理服务、轻量后端；
• Cloudflare R2：对象存储，类似 AWS S3；
• Cloudflare KV / D1 / Durable Objects：适合存储配置、轻量数据或构建边缘应用。

本文将以最常见的部署场景为主，完整讲解如何使用 Cloudflare 部署一个前端项目，并附带常用配置文件。文章内容包括：账号准备、域名接入、Pages 部署、Workers 部署、自定义域名、环境变量、重定向配置、安全响应头配置、常见问题等。

一、准备工作

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

1. Cloudflare 账号

访问 Cloudflare 官网：

https://www.cloudflare.com/

注册并登录账号。

Cloudflare 大部分基础功能都可以免费使用，包括：

• 免费 DNS；
• 免费 CDN；
• 免费 HTTPS；
• 免费 Pages；
• 免费 Workers 额度；
• 免费 WAF 基础防护。

对于个人博客、文档站、小型前端项目来说，免费套餐通常已经足够。

2. 一个前端项目

本文以常见的 Vite 项目为例，你可以替换成 Vue、React、Svelte、Astro、Next.js 静态导出项目等。

示例项目结构如下：

my-cloudflare-demo/
├── public/
├── src/
│   ├── assets/
│   ├── App.vue
│   └── main.ts
├── index.html
├── package.json
├── vite.config.ts
└── README.md

如果你还没有项目，可以使用以下命令创建一个 Vite 项目：

npm create vite@latest my-cloudflare-demo

进入目录：

cd my-cloudflare-demo

安装依赖：

npm install

本地运行：

npm run dev

如果页面可以正常打开，说明项目没有问题。

3. 一个 Git 仓库

Cloudflare Pages 支持直接从 GitHub、GitLab 部署项目。

建议将项目提交到 GitHub：

git init
git add .
git commit -m "init project"
git branch -M main
git remote add origin https://github.com/你的用户名/my-cloudflare-demo.git
git push -u origin main

如果你不想使用 Git，也可以使用 Wrangler 命令行工具上传部署，不过对于大多数项目，推荐使用 Git 自动部署。

二、将域名接入 Cloudflare

如果你只是想使用 Cloudflare Pages 默认域名，可以跳过本节。

Cloudflare Pages 默认会提供类似下面的访问地址：

https://your-project.pages.dev

如果你想使用自己的域名，例如：

https://example.com
https://www.example.com

就需要先把域名接入 Cloudflare。

1. 添加站点

登录 Cloudflare 后，点击：

Websites / 网站

然后选择：

Add a site / 添加站点

输入你的域名，例如：

example.com

Cloudflare 会扫描当前 DNS 记录，扫描完成后选择免费套餐即可。

2. 修改域名 NS 服务器

Cloudflare 会给你分配两条 Nameserver，例如：

alice.ns.cloudflare.com
bob.ns.cloudflare.com

你需要登录你的域名注册商后台，例如：

• 阿里云；
• 腾讯云；
• Namecheap；
• GoDaddy；
• Porkbun；
• Spaceship。

找到域名的 DNS 或 Nameserver 设置，将原有 NS 修改为 Cloudflare 提供的两条 NS。

修改后等待生效，一般需要几分钟到数小时不等。

当 Cloudflare 后台显示：

Active

说明域名已经成功接入 Cloudflare。

三、使用 Cloudflare Pages 部署前端项目

Cloudflare Pages 是部署静态网站最简单的方式。它支持从 Git 仓库自动拉取代码、构建并发布。

1. 创建 Pages 项目

进入 Cloudflare 控制台，点击：

Workers & Pages

然后选择：

Create application

再选择：

Pages

选择连接 Git 仓库：

Connect to Git

授权 Cloudflare 访问你的 GitHub 或 GitLab 账号。

选择你的项目仓库，例如：

my-cloudflare-demo

2. 配置构建参数

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

Framework preset: Vite
Build command: npm run build
Build output directory: dist
Root directory: /

如果你的项目在仓库子目录中，例如：

apps/web

则 Root directory 填写：

apps/web

常见框架构建目录如下：

配置完成后，点击部署即可。

四、示例配置文件

下面提供一套完整的前端项目配置文件，适合 Vite + Vue 或 Vite + React 项目参考。

1. package.json

{
  "name": "my-cloudflare-demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 0.0.0.0",
    "build": "vite build",
    "preview": "vite preview --host 0.0.0.0",
    "deploy": "npm run build && wrangler pages deploy dist"
  },
  "dependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "vite": "^5.0.0",
    "vue": "^3.4.0"
  },
  "devDependencies": {
    "wrangler": "^3.0.0",
    "typescript": "^5.0.0"
  }
}

说明：

• dev：本地开发；
• build：构建生产文件；
• preview：本地预览构建结果；
• deploy：使用 Wrangler 手动部署到 Cloudflare Pages；
• wrangler：Cloudflare 官方命令行工具。

如果你是 React 项目，将 Vue 相关依赖替换成 React 即可。

2. vite.config.ts

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  build: {
    outDir: "dist",
    assetsDir: "assets",
    sourcemap: false
  },
  server: {
    host: "0.0.0.0",
    port: 5173
  }
});

如果你的项目部署在子路径，例如：

https://example.com/docs/

需要设置 base：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  base: "/docs/",
  plugins: [vue()],
  build: {
    outDir: "dist"
  }
});

如果部署在根域名，例如：

https://example.com/

则不需要设置 base，或设置为：

base: "/"

3. _redirects

Cloudflare Pages 支持在构建输出目录中添加 _redirects 文件，用于配置路由重定向。

对于 Vue Router、React Router 等前端单页应用，刷新页面时可能出现 404。例如访问：

https://example.com/about

如果服务器找不到 /about 文件，就会返回 404。

解决方式是在 public 目录下新建 _redirects 文件：

/*    /index.html   200

完整示例：

# SPA 单页应用回退规则
/*    /index.html   200

对于 Vite 项目，public 目录里的文件会原样复制到 dist 中。因此最终部署后，Cloudflare Pages 能读取到该文件。

如果需要将旧地址跳转到新地址，可以这样写：

/old-page    /new-page    301
/blog/old-post    /blog/new-post    301

如果要将所有 HTTP 跳转到 HTTPS，通常不需要写 _redirects，Cloudflare 的 SSL/TLS 已经可以处理。

4. _headers

_headers 文件用于配置 HTTP 响应头。建议在 public 目录下新建 _headers 文件。

示例配置如下：

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate

说明：

• X-Frame-Options: DENY：防止页面被 iframe 嵌套；
• X-Content-Type-Options: nosniff：防止浏览器猜测 MIME 类型；
• Referrer-Policy：控制来源信息暴露；
• Permissions-Policy：限制摄像头、麦克风、定位等权限；
• Strict-Transport-Security：强制浏览器使用 HTTPS；
• 静态资源设置长期缓存；
• HTML 设置短缓存，方便版本更新。

需要注意的是，如果你的网站有被其他网站 iframe 嵌入的需求，就不要使用 X-Frame-Options: DENY。

5. .gitignore

node_modules
dist
.env
.env.local
.DS_Store
.cache
.wrangler

建议不要将 .env、构建产物、依赖目录提交到 Git 仓库。

五、使用 Wrangler 手动部署 Pages

虽然 Cloudflare Pages 支持 Git 自动部署，但有些场景下，你可能需要通过命令行手动部署，例如：

• 临时部署测试版本；
• CI/CD 自定义流程；
• 不想绑定 GitHub；
• 项目代码在私有环境中。

1. 安装 Wrangler

项目内安装：

npm install -D wrangler

或者全局安装：

npm install -g wrangler

登录 Cloudflare：

npx wrangler login

浏览器会打开授权页面，确认授权即可。

2. 本地构建

npm run build

构建成功后会生成：

dist/

3. 部署到 Pages

第一次部署时：

npx wrangler pages project create my-cloudflare-demo

然后执行：

npx wrangler pages deploy dist --project-name=my-cloudflare-demo

如果你已经在 Cloudflare 后台创建了 Pages 项目，只需要使用相同项目名即可。

你也可以在 package.json 中添加部署脚本：

{
  "scripts": {
    "deploy": "npm run build && wrangler pages deploy dist --project-name=my-cloudflare-demo"
  }
}

之后直接运行：

npm run deploy

六、配置环境变量

很多项目需要区分开发环境和生产环境，例如 API 地址不同：

开发环境：https://dev-api.example.com
生产环境：https://api.example.com

Vite 项目中，暴露给前端的环境变量必须以 VITE_ 开头。

1. 本地 .env.production

VITE_API_BASE_URL=https://api.example.com
VITE_APP_NAME=Cloudflare Demo

在代码中读取：

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

console.log(apiBaseUrl);

2. Cloudflare Pages 后台配置

进入 Pages 项目：

Settings -> Environment variables

添加变量：

VITE_API_BASE_URL=https://api.example.com
VITE_APP_NAME=Cloudflare Demo

Cloudflare Pages 支持分别配置：

• Production；
• Preview。

也就是说，你可以给正式环境和预览环境设置不同变量。

例如：

生产环境：

VITE_API_BASE_URL=https://api.example.com

预览环境：

VITE_API_BASE_URL=https://dev-api.example.com

七、绑定自定义域名

部署成功后，Cloudflare Pages 会给你一个默认域名，例如：

https://my-cloudflare-demo.pages.dev

如果你想绑定自己的域名，例如：

https://www.example.com

进入 Pages 项目：

Custom domains

点击：

Set up a custom domain

输入：

www.example.com

如果你的域名已经接入 Cloudflare，Cloudflare 会自动创建对应 DNS 记录。

通常会生成一条 CNAME：

www.example.com -> my-cloudflare-demo.pages.dev

如果你要绑定根域名：

example.com

Cloudflare 也可以自动处理，一般不需要你手动配置复杂记录。

八、SSL/TLS 配置建议

进入域名设置中的：

SSL/TLS

推荐选择：

Full

或：

Full (strict)

对于 Pages 项目，Cloudflare 会自动签发证书，因此一般不会有证书问题。

同时建议开启：

Always Use HTTPS

路径：

SSL/TLS -> Edge Certificates -> Always Use HTTPS

这样访问 HTTP 时会自动跳转到 HTTPS。

九、缓存配置建议

Cloudflare 默认会缓存静态资源，但你也可以通过 _headers 文件更精确控制。

建议策略：

1. HTML 不长期缓存

/*.html
  Cache-Control: public, max-age=0, must-revalidate

这样可以避免用户一直看到旧页面。

2. JS、CSS、图片长期缓存

现代构建工具通常会给资源文件加 hash，例如：

app.3f2a9c1.js
style.89abcde.css

文件名变化后，浏览器会自动加载新文件，因此可以长期缓存：

/assets/*
  Cache-Control: public, max-age=31536000, immutable

3. 更新后清理缓存

如果发现部署后页面仍然显示旧内容，可以在 Cloudflare 后台执行：

Caching -> Configuration -> Purge Cache

选择：

Purge Everything

一般情况下，Pages 新部署后会自动处理大部分缓存问题，不需要频繁手动清理。

十、部署 Cloudflare Workers

如果你的项目不只是静态页面，还需要接口、代理、简单后端逻辑，可以使用 Cloudflare Workers。

Workers 是运行在 Cloudflare 边缘节点上的 Serverless 代码，适合以下场景：

• 提供简单 API；
• 做请求转发；
• 修改响应头；
• 鉴权；
• A/B 测试；
• 边缘缓存；
• 简单爬虫接口；
• Webhook 接收服务。

1. 创建 Workers 项目

执行：

npm create cloudflare@latest my-worker

根据提示选择：

Worker

进入目录：

cd my-worker

安装依赖后，本地运行：

npm run dev

2. Worker 示例代码

src/index.ts：

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
    const url = new URL(request.url);

    if (url.pathname === "/api/hello") {
      return Response.json({
        message: "Hello Cloudflare Workers",
        time: new Date().toISOString()
      });
    }

    return new Response("Not Found", {
      status: 404,
      headers: {
        "Content-Type": "text/plain;charset=UTF-8"
      }
    });
  }
};

3. wrangler.toml

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

[vars]
APP_NAME = "My Cloudflare Worker"
API_VERSION = "v1"

部署：

npm run deploy

或者：

npx wrangler deploy

部署成功后，你会得到一个类似下面的地址：

https://my-worker.你的用户名.workers.dev

访问：

https://my-worker.你的用户名.workers.dev/api/hello

可以看到 JSON 返回。

十一、Cloudflare Pages Functions

如果你的前端项目部署在 Pages 上，又想添加少量 API，不一定要单独创建 Workers 项目。Cloudflare Pages 支持 Functions。

在项目根目录创建：

functions/

示例结构：

my-cloudflare-demo/
├── functions/
│   └── api/
│       └── hello.ts
├── public/
├── src/
├── package.json
└── vite.config.ts

functions/api/hello.ts：

export async function onRequestGet(context) {
  return Response.json({
    message: "Hello from Cloudflare Pages Functions",
    time: new Date().toISOString()
  });
}

部署后访问：

https://example.com/api/hello

就会返回：

{
  "message": "Hello from Cloudflare Pages Functions",
  "time": "2024-01-01T00:00:00.000Z"
}

Pages Functions 很适合给静态站点补充简单接口。

十二、前端调用 API 示例

假设你的 Pages Functions 提供了 /api/hello 接口，可以在前端这样调用：

async function getHello() {
  const res = await fetch("/api/hello");

  if (!res.ok) {
    throw new Error("请求失败");
  }

  return await res.json();
}

getHello().then(data => {
  console.log(data);
});

如果你的 API 在独立 Worker 中，例如：

https://api.example.com/api/hello

则需要配置跨域响应头。

Worker 示例：

const corsHeaders = {
  "Access-Control-Allow-Origin": "https://www.example.com",
  "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type,Authorization"
};

export default {
  async fetch(request: Request): Promise {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        status: 204,
        headers: corsHeaders
      });
    }

    return Response.json(
      {
        message: "Hello API"
      },
      {
        headers: corsHeaders
      }
    );
  }
};

如果你想允许所有来源访问，可以设置：

"Access-Control-Allow-Origin": "*"

但生产环境不建议随意使用 *，尤其是涉及登录、Token、用户数据的接口。

十三、推荐的完整项目结构

一个较完整的 Cloudflare Pages 项目结构如下：

my-cloudflare-demo/
├── functions/
│   └── api/
│       └── hello.ts
├── public/
│   ├── _headers
│   └── _redirects
├── src/
│   ├── assets/
│   ├── App.vue
│   └── main.ts
├── .gitignore
├── package.json
├── vite.config.ts
└── README.md

其中：

• src：前端源码；
• public：静态公共文件；
• _headers：响应头配置；
• _redirects：重定向与 SPA 回退配置；
• functions：Pages Functions API；
• package.json：项目依赖和脚本；
• vite.config.ts：构建配置。

十四、常见问题与解决方案

1. 部署后刷新页面 404

原因：前端使用了 history 模式路由，但 Cloudflare Pages 找不到对应文件。

解决：添加 _redirects：

/*    /index.html   200

2. 构建失败，提示 Node 版本不兼容

原因：Cloudflare Pages 默认 Node 版本可能与你项目要求不一致。

解决：在 Pages 项目的环境变量中添加：

NODE_VERSION=20

或者在项目中添加 .node-version 文件：

20

3. 环境变量读取不到

检查以下几点：

1. Vite 前端变量必须以 VITE_ 开头；
2. Cloudflare Pages 中变量需要区分 Production 和 Preview；
3. 修改环境变量后需要重新部署；
4. 本地 .env 文件不要提交到仓库。

4. 自定义域名无法访问

检查：

1. 域名是否已经接入 Cloudflare；
2. DNS 记录是否正确；
3. Pages Custom Domains 是否绑定成功；
4. SSL 证书是否签发完成；
5. 是否等待 DNS 生效。

5. 部署后样式或 JS 404

通常是构建路径错误。

如果你部署在根目录：

https://example.com/

vite.config.ts 中使用：

base: "/"

如果部署在子目录：

https://example.com/app/

使用：

base: "/app/"

十五、总结

使用 Cloudflare 部署项目的核心流程并不复杂：

1. 准备前端项目；
2. 提交到 GitHub 或 GitLab；
3. 在 Cloudflare Pages 中连接仓库；
4. 配置构建命令和输出目录；
5. 添加 _redirects 解决 SPA 刷新 404；
6. 添加 _headers 强化安全和缓存策略；
7. 绑定自定义域名；
8. 根据需要使用 Pages Functions 或 Workers 提供 API。

对于大多数个人站点、博客、文档站和前端项目来说，Cloudflare Pages 是一个非常优秀的免费部署平台。它部署简单、访问速度快、自动 HTTPS、支持 Git 自动构建，并且可以与 Workers、KV、D1、R2 等服务组合，构建更完整的全栈应用。

如果你只是部署静态页面，使用 Pages 即可；如果你需要轻量后端逻辑，可以使用 Pages Functions；如果你需要更灵活的边缘计算能力，则可以使用 Workers。合理选择部署方式，就能充分发挥 Cloudflare 的性能与全球网络优势。