Cloudflare 部署说明

Cloudflare 适合部署 Prompt Optimizer 的 Web 前端。当前 Cloudflare Dashboard 可能会把 GitHub 仓库导入到 Workers Static Assets 流程，而不是旧版 Pages 表单。两种方式都能部署静态前端，但如果你的界面出现“创建 Worker”“部署命令 npx wrangler deploy”，请优先按下面的 Workers 流程配置。

推荐方式：一键部署

公开仓库用户可以优先使用 Cloudflare 官方的一键部署按钮：

这个流程会把源仓库克隆到你的 GitHub/GitLab 账号下，并使用 Workers Builds 创建和部署 Worker。仓库根目录已经包含 wrangler.jsonc，用于告诉 Cloudflare Workers 如何构建 Web 前端、发布 packages/web/dist 静态资源，并为单页应用启用 index.html 回退。

需要注意：

• Deploy to Cloudflare 按钮要求源仓库是公开的 GitHub/GitLab 仓库。
• 如果你想使用私有仓库，或想手动限制 Cloudflare GitHub App 只访问指定仓库，请使用下面的手动导入方式。

备选方式：手动导入仓库

手动导入适合私有仓库、组织仓库、需要精细控制 GitHub App 权限，或一键部署按钮失败的场景。

1. Fork 项目到自己的 GitHub

   • 访问 prompt-optimizer 项目
   • 点击右上角的 "Fork"
   • 完成后，你会在自己的 GitHub 账号下拥有一份仓库副本

2. 在 Cloudflare 中导入仓库

   • 登录 Cloudflare Dashboard
   • 进入 Workers & Pages
   • 选择通过 GitHub/Git 仓库创建应用
   • 选择你 fork 后的 prompt-optimizer 仓库

3. 确认 Worker 设置

   如果界面显示“创建 Worker”，大多数配置可以保持默认。Worker 名称需要和根目录 wrangler.jsonc 中的 name 保持一致。

   配置项	推荐值
   Worker name	如果自动填入 prompt-optimizer，保持不变；否则改成 prompt-optimizer
   Root directory / Path	保持默认，通常是 / 或留空
   Build command	清空；如果自动填入 pnpm run build，请删除。wrangler.jsonc 已配置构建命令
   Deploy command	保持默认 npx wrangler deploy
   Non-production branch deploy command	保持默认 npx wrangler versions upload

4. 环境变量

   通常不需要手动配置构建环境变量。Cloudflare 会根据仓库里的 packageManager 和 engines 检测 pnpm 和 Node.js 版本。

   如果 Cloudflare 检测到的版本不正确，再在项目的构建环境变量中添加：

   NODE_VERSION=22
   PNPM_VERSION=10.6.1
   

   不要在公开 Cloudflare 站点中预置模型 API Key。所有 VITE_* 变量都会进入前端构建产物，访问者可以在浏览器下载到这些值。公开站点应让用户在应用界面的模型管理中自行填写自己的 API Key。

   只有在受控的私有部署中，才考虑预置 VITE_* 模型配置；同时应配合 Cloudflare Access，并使用可轮换、权限受限、费用受控的密钥。

5. 部署

   • 保存配置并开始部署
   • 部署成功后，Cloudflare Workers 会提供一个 *.workers.dev 域名；你也可以后续绑定自定义域名
   • 后续你的 fork 有新 commit 时，Cloudflare 会自动重新构建并部署

6. 同步上游更新

   • 在 GitHub 打开你 fork 的仓库
   • 当页面提示落后于 linshenkx/prompt-optimizer 时，点击 Sync fork
   • 同步产生新 commit 后，Cloudflare 会自动重新部署

备选方式：旧版 Cloudflare Pages 表单

如果你的 Cloudflare Dashboard 仍然显示 Create application -> Pages -> Connect to Git，也可以继续用 Pages 表单：

可选：访问控制

Cloudflare 部署不使用 Vercel 的 ACCESS_PASSWORD、middleware.js 或 api/auth.js。如果你想限制访问，推荐使用 Cloudflare Access：

1. 进入 Cloudflare Zero Trust
2. 创建一个 Self-hosted application
3. 绑定你的 Workers 或 Pages 域名
4. 配置允许访问的邮箱、域名、身份提供商或其他策略

这样访问请求会先经过 Cloudflare Access，再进入静态站点，不需要修改前端代码。

可选：访问分析

Cloudflare Web Analytics 可以在 Cloudflare 控制台启用，不需要安装类似 @vercel/analytics 的前端依赖。

需要注意：Prompt Optimizer 当前使用 hash 路由，因此 Cloudflare Web Analytics 可以统计站点访问和性能数据，但不会自动把 /#/xxx 这类 hash 内页面切换当作独立页面浏览。

和 Vercel 部署的区别

常见问题

修改环境变量后没有生效

Cloudflare 的构建环境变量需要重新部署后才会进入前端构建产物。保存环境变量后，请在 Deployments 中重新部署一次。

为什么界面显示的是 Worker，不是 Pages

Cloudflare 控制台现在可能会把 GitHub 静态站点导入到 Workers Static Assets 流程。这个项目是纯前端静态站点，使用 Workers 流程时由 wrangler.jsonc 负责构建命令和 packages/web/dist 静态资源目录，和 Pages 表单中的构建命令、构建产物目录作用相同。

如果部署日志出现 The Wrangler application detection logic has been run in the root of a workspace，说明 Wrangler 没有读到项目根目录的 wrangler.jsonc，于是尝试在 monorepo 根目录自动识别应用。请确认当前部署的提交已经包含 wrangler.jsonc；如果仍然报错，再把部署命令改成 npx wrangler deploy --config wrangler.jsonc，把非生产分支部署命令改成 npx wrangler versions upload --config wrangler.jsonc。

连接模型 API 失败怎么办

Cloudflare 部署的是纯前端页面，浏览器仍然会直接请求模型服务。如果模型服务不允许浏览器跨域访问，Web 版会失败。此时建议使用桌面版，或配置你自己的 API 中转服务。

Source: docs/user/deployment/cloudflare-pages.md