Cloudflare Pages 部署前端应用完全指南：React/Vue/Next.js 配置+报错解决

前言

上周末我花了两个小时撸了个 React 项目，做完之后特别兴奋，想赶紧部署到网上给朋友们看看。打开 Cloudflare Pages 的配置页面，看着 “Build Command” 和 “Build Output Directory” 这两个输入框，我愣了半小时。 Build Command 到底填什么？npm run build 还是 npm build？Output Directory 是 build 还是 dist？环境变量怎么设置？开发环境和生产环境怎么分开？ 不知道你有没有过类似的经历。明明代码在本地跑得好好的，一到部署就各种懵。看官方文档吧，全是英文，而且讲得比较笼统。找中文教程吧，要么过时了，要么只讲一半。 这篇文章我会用最接地气的方式，手把手带你把 React、Vue、Next.js 项目部署到 Cloudflare Pages。不仅给你完整的配置清单，还会分享那些坑我都踩过了，你看完就能直接上手。 这篇文章你会得到：

• React、Vue、Next.js 三大框架的完整部署配置清单（直接复制就能用）
• 环境变量的正确设置方法（区分开发和生产环境）
• 5 个最常见报错的解决方案（特别是 Next.js 的 nodejs_compat 错误）
• 我的真实踩坑经验分享

为什么我选择了 Cloudflare Pages？

可能你会问：已经有 Vercel 和 Netlify 了，为什么还要用 Cloudflare Pages？ 说实话，我一开始也是用 Vercel 的。不是 Vercel 不好，而是免费版确实有点限制。我做了几个小项目，加起来流量一个月就超了 100GB，Vercel 就开始限速了。 后来我对比了一下三家平台，发现 Cloudflare Pages 在免费套餐上真的很香：

• 个人博客、作品集网站
• 中小型前端项目（SPA、静态站点）
• 需要全球加速的项目
• 流量不确定的项目（免费无限流量真香） 不太适合的场景：
• 需要复杂 SSR 功能的大型 Next.js 应用（CF Pages 对 Next.js 的支持不如 Vercel 完善）
• 需要频繁构建的项目（每月 500 次构建限制）
• 需要使用 Vercel 特有功能的项目（比如 Edge Middleware）

部署前的准备工作

在开始之前，你需要：

1. 注册 Cloudflare 账号
   • 去 Cloudflare 官网 注册一个账号（免费）
   • 验证邮箱就可以开始用了
2. 准备你的代码仓库
   • 把代码推送到 GitHub 或 GitLab
   • CF Pages 会直接从你的 Git 仓库拉代码构建
3. 了解你的项目构建配置
   • 你用的是 Create React App 还是 Vite？
   • 构建命令是什么？（通常是 npm run build）
   • 构建产物在哪个目录？（CRA 是 build，Vite 是 dist） 好了，准备工作做完，我们开始实战部署。

React 应用部署完整流程

React 是最常用的前端框架之一，我自己部署过好几个 React 项目到 CF Pages，整理了一套靠谱的配置清单。

快速创建 React 项目（如果你还没有项目）

如果你想跟着操作但手上没有现成的项目，可以快速创建一个：

# 方式1：使用 Vite（推荐，构建更快）
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# 方式2：使用 Create React App（经典方式）
npx create-react-app my-react-app
cd my-react-app

我个人更推荐用 Vite，构建速度真的快很多。CRA 项目大了之后构建会比较慢。

Cloudflare Pages 配置清单

登录 Cloudflare Dashboard，进入 Pages 页面，点击”创建项目”→“连接到 Git”，选择你的 GitHub 仓库。 然后你会看到配置页面，这里是关键： 配置项说明：

• Vite 项目的 Framework preset 选”None”就可以，CF Pages 会自动识别
• CRA 项目可以选”Create React App”预设，配置会自动填充
• 输出目录最容易搞错：Vite 是 dist，CRA 是 build，千万别填反了

环境变量设置

React 项目的环境变量有个特殊要求：必须带特定前缀才能在客户端访问。 Vite 项目：

• 前缀必须是 VITE_
• 示例：VITE_API_URL、VITE_API_KEY CRA 项目：
• 前缀必须是 REACT_APP_
• 示例：REACT_APP_API_URL、REACT_APP_API_KEY 设置方法：

1. 在 Cloudflare Pages 中设置（推荐）：
   • 进入项目 → Settings → Environment variables
   • 点击”Add variable”
   • 选择环境：Production（生产）或 Preview（预览）
   • 输入变量名和值
2. 代码中使用：

// Vite 项目
const apiUrl = import.meta.env.VITE_API_URL;
// CRA 项目
const apiUrl = process.env.REACT_APP_API_URL;

本地开发环境变量： 在项目根目录创建 .env.local 文件：

# Vite 项目
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-api-key-here
# CRA 项目
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key-here

重要提醒：

• .env.local 文件不要提交到 Git！在 .gitignore 中添加 .env*.local
• 修改环境变量后，必须重新部署才能生效

解决 SPA 路由 404 问题

如果你的 React 项目使用了 React Router，部署后可能会遇到一个坑：刷新页面就 404。 这是因为 SPA 项目所有路由都需要指向 index.html，但服务器默认会去找对应的文件。 解决方法： 在项目的 public 目录下创建一个 _redirects 文件：

/* /index.html 200

就这一行代码，告诉服务器：所有路径都重定向到 index.html，并返回 200 状态码。 保存后重新部署，路由就正常了。

验证部署成功

点击”Save and Deploy”后，CF Pages 会开始构建。你可以在”Deployments”页面查看构建日志。 构建成功的标志：

• 日志中显示 “Success: Deployed to…”
• 给你一个 xxx.pages.dev 的访问链接
• 点开能看到你的项目 如果构建失败：
• 查看日志找到错误信息
• 常见原因：
  • 输出目录写错了（Vite 写成 build，或 CRA 写成 dist）
  • Node 版本过低（需要设置 NODE_VERSION=18 环境变量）
  • 依赖安装失败（检查 package.json）

Vue 应用部署完整流程

Vue 的部署和 React 差不多，但也有一些细节需要注意。

快速创建 Vue 项目（可选）

# 方式1：使用 Vite（推荐）
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# 方式2：使用 Vue CLI
vue create my-vue-app
cd my-vue-app

同样推荐 Vite，性能更好。

Cloudflare Pages 配置清单

• Vue CLI 和 Vite 的输出目录都是 dist（和 React 不太一样）
• 环境变量前缀不同：Vite 用 VITE_，Vue CLI 用 VUE_APP_

环境变量设置

Vite + Vue 项目：

# .env.local
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My Vue App

Vue CLI 项目：

# .env.production
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_TITLE=My Vue App

代码中使用：

// Vite 项目
const apiUrl = import.meta.env.VITE_API_BASE_URL;
// Vue CLI 项目
const apiUrl = process.env.VUE_APP_API_BASE_URL;

Vue Router 路由配置

如果你用了 Vue Router，特别是 History 模式，一定要配置重定向，不然刷新页面会 404。 方式1：使用 _redirects 文件（推荐） 在 public 目录下创建 _redirects 文件：

/* /index.html 200

方式2：在 vite.config.js 中配置（Vite 项目） 如果你的项目不在根目录部署，需要配置 base：

// vite.config.js
export default {
  base: '/', // 确保是根路径
}

常见问题排查

问题1：静态资源 404 检查 vue.config.js（Vue CLI）或 vite.config.js（Vite）中的 publicPath 或 base 配置：

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/', // 确保是根路径
}

问题2：Vite 构建报错 “Unknown file extension” 这通常是 Node 版本太低导致的。在 CF Pages 环境变量中添加：

NODE_VERSION=18

然后重新部署。

Next.js 应用部署完整流程（重点！）

Next.js 在 Cloudflare Pages 上的部署，说实话，是这三个框架里最复杂的。我第一次部署的时候，被 nodejs_compat 这个错误卡了一下午，网上搜了好多资料才搞定。 老实讲，如果你的 Next.js 项目需要大量 SSR 功能，我建议还是用 Vercel。但如果是静态站点或者简单的 SSR，CF Pages 完全够用，而且免费流量无限真的很香。

Next.js 部署的特殊性

在开始之前，你需要知道几个重要的点：

1. Cloudflare Pages 不是专为 Next.js 设计的（不像 Vercel），需要一些额外配置
2. 有两种部署方式：静态导出（最简单）和 SSR 模式（需要适配器）
3. 如果要用 SSR，需要使用 @opennextjs/cloudflare 适配器（旧的 @cloudflare/next-on-pages 已经废弃了）

方式1：静态导出（最简单，推荐新手）

如果你的 Next.js 项目不需要服务端渲染、API Routes、ISR 等功能，静态导出是最简单的方式。 适用场景：

• 个人博客
• 文档站点
• 纯展示型网站
• 不需要动态数据的项目 配置步骤：

1. 修改 next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 关键：开启静态导出
  images: {
    unoptimized: true, // CF Pages 不支持 Next.js Image Optimization
  },
}
module.exports = nextConfig

2. Cloudflare Pages 配置： | 配置项 | 填写内容 | |--------|---------| | Framework preset | Next.js (Static HTML Export) | | Build command | npm run build | | Build output directory | out | | Root directory | / (默认) |
3. 部署： 保存配置后直接部署就可以了。构建成功后，你会得到一个静态站点。 限制：

• ❌ 不支持 API Routes
• ❌ 不支持 ISR (Incremental Static Regeneration)
• ❌ 不支持 Server Components
• ❌ 不支持动态路由的服务端渲染 如果这些限制你都能接受，静态导出就很够用了。

方式2：SSR 模式（使用 OpenNext 适配器）

如果你需要 API Routes、SSR、动态路由等功能，就得用适配器了。这部分稍微复杂一点，但我会尽量讲清楚。 安装适配器：

npm install @opennextjs/cloudflare

配置 next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 不需要设置 output: 'export'
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Cloudflare Pages 配置：

1. 进入你的项目 → Settings → Functions
2. 找到 Compatibility flags 部分
3. 点击 Configure Production compatibility flag
4. 添加标志：nodejs_compat
5. 设置 Compatibility Date：至少 2024-09-23（或更新的日期） 注意：

• Production 环境和 Preview 环境都要设置
• 不设置这个标志，部署后会直接 500 错误 Edge Runtime 要求： 如果你用了 API Routes 或者 Server Components，必须添加 Edge Runtime 声明：

// app/api/hello/route.js
export const runtime = 'edge'; // 关键！必须加这行
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

// pages/api/hello.js (Pages Router)
export const config = {
  runtime: 'edge', // 关键！必须加这行
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

所有需要服务端运行的文件都要加这个声明，不然部署会失败。

Next.js 环境变量设置

Next.js 的环境变量分两种： 1. 客户端变量（必须带前缀）：

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Next.js Site

2. 服务端变量（不需要前缀）：

# .env.local
DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

在 Cloudflare Pages 中设置： 进入 Settings → Environment variables，添加变量时选择对应的环境（Production/Preview）。 代码中使用：

// 客户端
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// 服务端（API Route 或 Server Component）
const dbUrl = process.env.DATABASE_URL;

Next.js 常见报错及解决方案（重点！）

这部分是我踩过的坑，整理了 5 个最常见的报错和解决方法。

错误 1：nodejs_compat is not defined 或 500 错误

错误信息：

Error: The global scope does not support nodejs_compat

或者部署成功但打开就是 500 错误。 原因： 缺少 nodejs_compat 兼容性标志。 解决方法：

1. 进入项目 → Settings → Functions
2. 找到 Compatibility flags
3. 在 Production 和 Preview 环境都添加 nodejs_compat
4. 重新部署 这个我当时卡了很久，设置完立马就好了。

错误 2：部署成功但页面显示 404

症状：

• 构建日志显示成功
• 访问 xxx.pages.dev 显示 404
• 或者只有首页能访问，其他页面 404 原因：
• 没有正确配置 Edge Runtime
• 或者 Build output directory 写错了 解决方法：

1. 检查所有 API Routes 和 Server Components 是否添加了 runtime = 'edge'
2. 确认 Build output directory 是 .worker-next（用适配器）或 out（静态导出）
3. 如果是静态导出，检查是否创建了 _redirects 文件

错误 3：FinalizationRegistry is not defined

错误信息：

ReferenceError: FinalizationRegistry is not defined

原因： Compatibility Date 过旧，不支持新的 JavaScript 特性。 解决方法：

1. 进入 Settings → Functions
2. 将 Compatibility Date 更新到 2024-09-23 或更新
3. 重新部署

错误 4：构建时间过长或失败

症状：

• 构建超过 10 分钟还没完成
• 或者显示”Build exceeded maximum duration” 原因：
• 使用了 Turbopack（next dev --turbo）
• 或者项目太大，依赖太多 解决方法：

1. 检查 Build command，确保是 npx @opennextjs/cloudflare，不要用 --turbo 参数
2. 清理不必要的依赖：npm prune
3. 考虑用静态导出方式（如果可以）

错误 5：Image Optimization 报错

错误信息：

Error: Image Optimization using Next.js' default loader is not compatible with `output: 'export'`.

原因： Cloudflare Pages 不支持 Next.js 的 Image Optimization API。 解决方法： 在 next.config.js 中禁用：

module.exports = {
  images: {
    unoptimized: true,
  },
}

如果需要图片优化，可以用：

• Cloudflare Images（付费服务）
• 第三方 CDN（如 Cloudinary）
• 自己处理图片（压缩后再上传）

环境变量管理进阶

环境变量这块我刚开始也挺懵的，特别是开发环境、预览环境、生产环境怎么区分。后来摸索出一套比较清晰的管理方法。

区分三种环境

Cloudflare Pages 支持三种环境：

在 Cloudflare Dashboard 中设置

进入项目 → Settings → Environment variables 你会看到两个标签页：

• Production：生产环境变量
• Preview：预览环境变量 推荐设置方式：

1. 生产环境变量（真实的 API Key、数据库连接等）：
   • 类型选 Secret（加密存储，日志中不显示）
   • 示例：API_KEY=prod-key-12345
2. 预览环境变量（测试用的 API Key）：
   • 可以选 Plain text
   • 示例：API_KEY=test-key-67890

本地开发环境变量

推荐文件结构：

my-project/
├── .env.local          # 本地开发变量（不提交到 Git）
├── .env.example        # 变量模板（提交到 Git）
├── .gitignore          # 忽略敏感文件

.env.local 示例：

# API 配置
VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
# 功能开关
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
# 第三方服务
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

.env.example 示例：

# API 配置
VITE_API_BASE_URL=your-api-url-here
VITE_API_KEY=your-api-key-here
# 功能开关
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

重要提醒：

• .env.local 不要提交到 Git
• .env.example 提交到 Git，方便团队成员参考
• 在 .gitignore 中添加：.env*.local

环境变量前缀速查表

不同框架的前缀要求不一样，我整理了一个表格方便查阅：

• 如果变量要在浏览器中访问，必须带前缀
• 如果变量只在服务端用（API Key、数据库密码），不需要前缀

环境变量不生效怎么排查？

我遇到过好几次环境变量设置了但不生效的情况，总结了一个排查清单： 排查步骤：

1. 检查前缀是否正确
   • Vite 项目用了 REACT_APP_ 前缀？（应该用 VITE_）
   • Next.js 客户端变量忘了加 NEXT_PUBLIC_？
2. 确认已重新部署
   • 修改环境变量后，必须触发新的部署才能生效
   • 可以推送一个小改动到 Git，或者在 Dashboard 中点”Retry deployment”
3. 验证环境是否正确
   • 你改的是 Production 环境，但访问的是 Preview 链接？
   • 或者反过来？
4. 查看构建日志
   • 在构建日志中搜索变量名
   • 确认变量被正确读取（注意：Secret 类型的变量不会显示值）
5. 检查代码中的引用方式

   // ❌ 错误（Vite 项目）
   const apiUrl = process.env.VITE_API_URL;
   // ✅ 正确（Vite 项目）
   const apiUrl = import.meta.env.VITE_API_URL;

进阶技巧与最佳实践

部署成功只是第一步，这些进阶技巧能让你的项目更专业。

自定义域名绑定

用 xxx.pages.dev 域名总感觉不够专业，绑定自己的域名很简单。 步骤：

1. 在 Cloudflare Pages 中添加域名：
   • 进入项目 → Custom domains
   • 点击 Set up a custom domain
   • 输入你的域名（如 blog.example.com）
2. 配置 DNS 记录：
   • 如果域名已经在 Cloudflare 上，会自动添加 CNAME 记录
   • 如果域名在其他服务商，需要手动添加：

     CNAME  blog  your-project.pages.dev

3. 等待 SSL 证书生成：
   • Cloudflare 会自动申请免费的 SSL 证书
   • 通常 5-10 分钟就好了 然后你就可以用自己的域名访问了，而且自动支持 HTTPS。

Preview Deployments（预览部署）

这个功能特别适合团队协作。每次你推送代码到非主分支或创建 Pull Request，CF Pages 会自动创建一个预览环境。 怎么用：

1. 创建新分支：

   git checkout -b feature/new-button

2. 修改代码并推送：

   git add .
   git commit -m "Add new button"
   git push origin feature/new-button

3. CF Pages 自动构建并生成预览链接：

   https://abc123.your-project.pages.dev

4. 在 PR 中查看预览链接，测试新功能
5. 合并到主分支后，自动部署到生产环境 好处：

• 每个功能分支都有独立的预览环境
• 可以让产品经理、设计师直接看效果
• 不会影响生产环境

构建缓存优化

如果你的项目每次构建都很慢，可以试试优化构建缓存。 在项目中添加缓存配置： Cloudflare Pages 会自动缓存 node_modules，但你可以进一步优化：

1. 使用 pnpm（比 npm 快）：

   # 在项目中添加 .npmrc
   echo "package-manager=pnpm" > .npmrc

2. 在 CF Pages 中设置：
   • Build command 改为：pnpm install && pnpm build
3. 移除不必要的依赖：

   npm prune

我的经验： 切换到 pnpm 后，构建时间从 5 分钟降到了 2 分钟，效果还挺明显的。

配置自定义 Headers

如果你想添加自定义 HTTP Headers（如安全策略、缓存控制），可以在项目根目录创建 _headers 文件：

# _headers 文件示例
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer-when-downgrade
/static/*
  Cache-Control: public, max-age=31536000, immutable
/api/*
  Cache-Control: no-cache

保存后重新部署，Headers 就生效了。

总结

写了这么多，其实核心就三点： 1. 搞清楚你的项目构建配置

• Build command 是什么？（通常是 npm run build）
• 输出目录在哪？（Vite 是 dist，CRA 是 build，Next.js 看情况）
• 需要什么环境变量？（注意前缀要求） 2. 重点关注常见的坑
• Next.js 的 nodejs_compat 标志（不设置就 500 错误）
• 环境变量的前缀（Vite 用 VITE_，Next 用 NEXT_PUBLIC_）
• SPA 路由的 404 问题（记得加 _redirects 文件） 3. 善用 Preview 环境
• 不要直接在生产环境测试
• 用分支创建 Preview 环境
• 测试没问题再合并到主分支 说实话，Cloudflare Pages 用起来真的没那么难，主要是第一次配置的时候需要花点时间。一旦配好了，之后就是 Git Push 自动部署，非常省心。 而且免费无限流量这点真的太香了，我现在几个个人项目全放在 CF Pages 上，完全没有流量焦虑。 如果你遇到问题：
• 先看看这篇文章的”常见报错”部分，大部分坑我都踩过了
• 查看构建日志，错误信息会告诉你哪里出问题了
• 官方文档虽然是英文，但还挺详细的：Cloudflare Pages Docs 下一步你可以：
• 立即部署你的第一个项目到 Cloudflare Pages
• 试试绑定自定义域名
• 体验一下 Preview Deployments 的便利 有问题欢迎在评论区留言，我看到会回复的。祝你部署顺利！

发布于: 2025年12月1日 · 修改于: 2025年12月4日

Easton

技术开发