Cloudflare pages应用纯静态部署

Table of contents

Cloudflare Workers and Pages

cloudflare workers and pages 当前版本已经更新，和网上很多所谓的教程完全不一样，现在的 cloudflare 是没有分开这两种部署，而是集合在一个模块里，它通过你的项目的部署配置文件 wrangler.jsonc 和你应用真实情况，判定你是纯静态还是需要 workders。

也就是已经没有所谓的专门的 cloudflare pages 页面或者功能了。

React Vue 等纯静态项目部署配置

{
    "name": "jamie-ibili",
    "compatibility_date": "2026-04-09",
    "assets": {
        "directory": "./dist",
        "not_found_handling": "single-page-application"
    }
}wrangler.jsonc

新建一个 wrangler.jsonc 放在你的项目根目录中

构建报错

我遇到的构建报错查了很久才解决，我使用的是 pnpm build 命令进行构建，但是如果 cloudflare 的默认使用的 pnpm 版本和你不一致，就会构建失败，你需要在应用设置中，在 构建 的 变量和机密 中，新建一个变量 PNPM_VERSION，值就是项目使用的 pnpm -v 得到的版本号，再重新构建即可。

部署报错

碰到过两种部署报错：

• 一种是没有 wrangler.jsonc 文件导致 cloudflare 尝试使用 workers 模式帮我部署静态项目，导致部署失败。
• 一种是单纯的网络波动导致的部署失败，重新构建一次即可。

部署命令都是默认的：npx wrangler deploy 我没修改过。

Next.js 等使用 SSR 的框架，等我有空后面补充进来，他们因为使用了 workers ，配置会不一样

传统js项目

除了 vue react 等 js 框架项目，传统的 html+jquery 这种组合的静态项目部署会更加简单，不需要配置 wrangler.jsonc，直接部署就行，如果你使用 github 自动拉取的，cloudflare 在你部署后，会给你推一个合并请求，里面会帮你新增一个 wrangler.jsonc，类似如下内容：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "youngift",
  "compatibility_date": "2025-09-27",
  "observability": {
    "enabled": true
  },
  "assets": {
    "directory": "."
  },
  "compatibility_flags": [
    "nodejs_compat"
  ]
}wrangler.jsonc

注意这里的 observability 静态站一般都没必要开。