Cloudflare：先判断你部署的是“文件”还是“运行中的代码”

Pages 适合什么

Vite、VitePress 等项目构建后生成 HTML、CSS、JavaScript 静态文件，可以由 Pages 发布。

本站路线：

docs Markdown
  ↓ npm run build
.vitepress/dist
  ↓ Cloudflare Pages
公开域名

Workers 适合什么

Workers 运行服务器端代码，可以处理请求、鉴权、API 和边缘逻辑。它不是传统长期占用一台服务器的进程，运行模型和平台能力要按 Workers 当前限制设计。

Pages 部署必须填写的三个核心值

Root directory / 工作目录

Monorepo 中决定从哪个子目录开始安装和构建。填错会找不到 package.json。

Build command / 构建命令

来自 package.json scripts，例如：

npm run build

Build output directory / 输出目录

平台最后发布哪个文件夹。

Vite          dist
VitePress     .vitepress/dist

不要把 src 或 Markdown 原文件直接当作浏览器成品。

从 Git 部署和直接上传的区别

Git 集成

Push 到指定分支后，平台自动获取 commit、安装依赖、构建并发布。优点是版本和部署能对应。

Direct Upload / CLI

你先在本地构建，再上传产物。适合明确控制构建结果，但必须确认上传目录是最新产物。

两种方式都能发布，不要在同一个问题里来回切换而不记录当前来源。

环境变量放哪里

本地 .env 不会自动跟着 Git 上线。Cloudflare 项目设置中要为对应环境配置变量。

Preview      预览部署
Production   正式环境

变量只配置到 Preview，正式域名仍可能缺失。

前端构建变量会进入浏览器，不要放秘密；Workers 服务器变量按平台秘密配置管理。

部署记录怎样看

打开某次 Deployment，先确认：

来源分支和 commit
安装命令
构建命令
第一条错误
输出目录
部署状态
预览 URL

不要只看最下面红色 Build failed。

本地正常、Cloudflare 失败的常见原因

package manager 不一致
Node 版本不同
输出目录填错
环境变量只存在本地
文件名大小写不一致
Monorepo 工作目录错误
Workers Runtime 不支持某个 Node API

平台部署成功但自定义域名没更新

按顺序检查：

1. 平台提供的 pages.dev 预览地址是不是新版本。
2. 自定义域名是否连接到正确项目。
3. DNS 记录是否正确。
4. 是否有缓存规则或 Service Worker 保留旧内容。

如果预览地址都是旧内容，先别查 DNS，说明部署版本本身就不对。

一份落地检查表

本地 npm run build 成功
输出目录真实存在
部署来源 commit 正确
平台构建命令正确
Production 变量齐全
平台预览 URL 是新版本
自定义域名返回新版本
关键按钮实际操作成功

官方参考：Cloudflare Pages 文档和Cloudflare Workers 文档。

VitePress 构建成功，但 Cloudflare 输出目录填成 docs。最可能出现什么？

答案：平台会发布错误目录，可能看到原始文件、404 或空站点。VitePress 通常应该发布 .vitepress/dist。