本地开发与部署

本文说明如何在本仓库中运行官网与文档，并部署到 Cloudflare Pages。

环境要求

• Node.js 18+
• pnpm 9+（推荐）

安装依赖

在项目根目录执行：

pnpm install

原生模块（esbuild、@tailwindcss/oxide）的构建许可已写入 pnpm-workspace.yaml 的 allowBuilds，CI 环境无需手动执行 approve-builds。

运行官网（Vite + React）

# 开发模式，默认 http://localhost:5173
pnpm dev

# 生产构建，输出到 dist/
pnpm build

# 本地预览构建结果
pnpm preview

运行文档（VitePress）

# 开发模式，默认 http://localhost:5173（若官网已占用会自动换端口）
pnpm dev:docs

# 构建文档，输出到 docs/.vitepress/dist/
pnpm build:docs

# 预览文档构建结果
pnpm preview:docs

一键构建全部

pnpm build:all

Cloudflare Workers 与 Pages 的区别

	Cloudflare Pages	Cloudflare Workers
用途	托管静态网站（HTML/CSS/JS）	运行服务端 JavaScript 代码
适合本项目	✅ 官网、VitePress 文档	❌ 不适合纯静态站
控制台特征	有「构建输出目录」字段	有「部署命令: wrangler deploy」，无输出目录
部署方式	构建 → 上传 dist 目录	wrangler deploy + wrangler.toml
免费额度	无限静态请求	按请求次数计费
自定义域名	支持	支持

本项目是 Vite 静态站 + VitePress 文档，应使用 Cloudflare Pages。

如果你误建了 Workers 项目

在 Cloudflare 控制台删除现有 Workers 项目，重新创建 Pages 项目（Workers & Pages → Create → Pages → Connect to Git）。

部署到 Cloudflare Pages

前置条件

1. 拥有 Cloudflare 账户
2. 完成身份验证：npx wrangler login 或设置 CLOUDFLARE_API_TOKEN

创建 Pages 项目（Git 自动部署，推荐）

1. 进入 Cloudflare Dashboard → Workers & Pages → Create
2. 选择 Pages → Connect to Git
3. 选择仓库 cofroute/Realtimetranslationsoftwarewebsite
4. 同一仓库需创建 两个 Pages 项目（官网 + 文档）

官网项目：

配置项	值
项目名称	voxa-website（可自定义）
生产分支	main
框架预设	None
构建命令	corepack enable && corepack prepare pnpm@9.15.9 --activate && pnpm install && pnpm build
构建输出目录	dist
根目录	/
环境变量	NODE_VERSION = 20.19.0

文档项目：

配置项	值
项目名称	voxa-docs（可自定义）
生产分支	main
框架预设	None（不要选 VitePress，见下方说明）
构建命令	corepack enable && corepack prepare pnpm@9.15.9 --activate && pnpm install && pnpm build:docs
构建输出目录	docs/.vitepress/dist
根目录	/

环境变量（两个项目均建议设置）：

变量	值
NODE_VERSION	20.19.0

文档项目勿选「VitePress」框架预设

选 VitePress 预设会启用 asdf 版本管理，要求 .tool-versions 精确版本，且与 monorepo 结构冲突，容易导致 error code 126 构建失败。请选 None，手动填写构建命令和输出目录。

不要使用 .tool-versions

Cloudflare 检测到 .tool-versions 会走 asdf 安装流程，asdf 没有 pnpm 插件，写入 pnpm x.x.x 会报 pnpm plugin is not installed。Node 版本请用环境变量 NODE_VERSION=20.19.0 或仓库内的 .nvmrc / .node-version。

勿使用 approve-builds

pnpm approve-builds 是本地交互命令，CI 中不存在。不要写入构建命令。

没有「部署命令」字段

Pages 项目只需填写「构建命令」和「构建输出目录」，不需要 npx wrangler deploy。构建完成后 Cloudflare 自动发布静态文件。

命令行一键部署

npx wrangler login

# Windows
pnpm deploy:all        # 同时部署官网 + 文档
pnpm deploy:website    # 仅官网
pnpm deploy:docs       # 仅文档

可通过环境变量自定义项目名：

$env:CF_PAGES_PROJECT_WEBSITE = "my-website"
$env:CF_PAGES_PROJECT_DOCS = "my-docs"