Cloudflare Pages部署Vite项目404错误如何解决？

Question

在使用 Cloudflare Pages 部署基于 Vite 构建的前端项目时，常见问题是在路由跳转或刷新页面时出现 404 错误。该问题通常出现在启用 HTML5 History 模式的 Vue Router 或 React Router 中，由于 Cloudflare Pages 默认未配置重定向规则，导致无法正确返回 index.html 文件以支持客户端路由。当访问 `/about` 等非根路径时，服务器尝试查找对应静态资源，而实际文件不存在，从而返回 404。如何配置 Cloudflare Pages 支持单页应用（SPA）的路由 fallback，成为部署过程中的关键问题。

Answer 1

1. 问题背景与现象描述

在使用 Cloudflare Pages 部署基于 Vite 构建的前端项目时，开发者常遇到路由跳转或页面刷新后出现 404 错误。该问题主要出现在使用 Vue Router 或 React Router 启用 HTML5 History 模式 的单页应用（SPA）中。

当用户访问 /about、/user/profile 等非根路径时，浏览器会向服务器发起请求，期望获取对应资源。然而，这些路径在静态文件系统中并不存在实际对应的 HTML 文件，Cloudflare Pages 默认行为是返回 404，而非将请求重定向至 index.html 进行客户端路由接管。

2. 核心机制分析：为何会出现 404？

• 静态托管限制：Cloudflare Pages 本质上是一个静态站点托管平台，其默认处理逻辑为“按路径查找静态资源”。
• 客户端路由 vs 服务端路由：SPA 的路由由 JavaScript 在浏览器中控制，但首次请求仍需服务器返回 index.html 才能启动应用。
• History API 的副作用：虽然前端可通过 pushState 跳转，但刷新页面时请求直达服务器，无法触发前端路由逻辑。
• 缺少 fallback 配置：未显式告知服务器“所有未知路径应返回 index.html”，导致路由失效。

3. 解决方案概览

方案	实现方式	适用场景	维护成本
_redirects 文件	根目录添加 _redirects，配置 /* /index.html 200	通用 SPA 项目	低
cloudflare-pages.toml	使用 edge_bundling 和 routes 配置 fallback	高级部署需求	中
自定义构建脚本	构建后注入重定向规则	CI/CD 流水线集成	高

4. 实践步骤一：通过 _redirects 文件配置 fallback

最简单有效的方法是在项目根目录（与 index.html 同级）创建 _redirects 文件，并写入以下内容：

/* /index.html 200

该规则表示：所有路径匹配 /* 的请求，均返回 /index.html 内容，并以 HTTP 200 状态码响应，从而让前端路由接管渲染流程。

注意：200 是关键，它代表“重写（rewrite）”而非“重定向（redirect）”。若使用 301 或 302，会导致浏览器跳转，破坏 SPA 行为。

5. 实践步骤二：使用 cloudflare-pages.toml 配置高级路由

对于更复杂的路由控制，可使用 cloudflare-pages.toml 文件进行精细化管理。示例如下：

[build]
  command = "npm run build"
  publish = "dist"

[[routes]]
  pattern = "/*"
  url = "/index.html"
  status = 200
  override = true

此配置在构建阶段声明路由规则，支持模式匹配、状态码控制和优先级覆盖，适合多环境或多入口应用。

6. 构建流程整合：Vite 项目中的最佳实践

结合 Vite 的构建输出，建议在 vite.config.js 中确保输出结构清晰：

export default defineConfig({
  build: {
    outDir: 'dist',
    emptyOutDir: true,
  },
})

并在 CI/CD 中自动注入 _redirects 文件。例如，在 package.json 添加 postbuild 脚本：

"scripts": {
  "build": "vite build",
  "postbuild": "echo '/* /index.html 200' > dist/_redirects"
}

7. 验证与调试策略

部署后可通过以下方式验证 fallback 是否生效：

1. 直接访问 https://your-site.pages.dev/about，检查是否正常加载页面。
2. 打开浏览器开发者工具，查看 Network 面板中该请求的状态码是否为 200，且返回内容为 index.html。
3. 尝试刷新页面，确认无 404 报错。
4. 使用 curl 命令测试：curl -I https://your-site.pages.dev/nonexistent-path，应返回 200。

8. 进阶思考：边缘函数与动态路由的未来可能

随着 Cloudflare 支持 Workers & Pages Functions，未来可通过边缘函数实现更智能的路由分发。例如：

// functions/_middleware.ts
export const onRequest: PagesFunction = async (context) => {
  const { request } = context;
  const url = new URL(request.url);
  
  // 排除静态资源
  if (url.pathname.match(/\.(js|css|png|jpg|svg)$/)) {
    return await context.next();
  }

  // SPA fallback
  return Response.redirect('/index.html', 200);
};

此方式允许在边缘层进行逻辑判断，实现动静分离、身份验证前置等高级功能。

9. 故障排查清单

当 fallback 未生效时，可按以下流程图进行排查：

graph TD
    A[出现404错误] --> B{是否配置_redirects或pages.toml?}
    B -- 否 --> C[添加/* /index.html 200规则]
    B -- 是 --> D{文件是否位于正确目录?}
    D -- 否 --> E[移至dist或根目录]
    D -- 是 --> F{构建后是否被覆盖?}
    F -- 是 --> G[使用postbuild脚本重新生成]
    F -- 否 --> H[检查CF Pages部署日志]
    H --> I[确认最新提交已部署]
    I --> J[测试直接URL访问]

10. 总结性延伸：SPA 部署范式的演进

从早期的 hash 模式迁移到 history 模式，再到如今的边缘计算支持，SPA 的部署正从“规避服务器限制”走向“主动利用边缘能力”。Cloudflare Pages 作为 JAMstack 架构的重要组成部分，其对 fallback 路由的支持不仅是技术细节，更是现代前端工程化成熟度的体现。

掌握此类配置，不仅解决当前问题，更为后续接入 SSR、ISR、边缘缓存等高级特性打下基础。