CodFlow 商店前端 — Vercel 部署手册
cod-astro/theme01 是 CodFlow 面向客户的商店前端主题（基于 Astro 7）。
虽然 CodFlow 后端（cod-server）和商家控制台（cod-client-astro）运行在 Cloudflare Workers 上（使用 D1、R2 和 KV），但商店前端支持动态部署目标（DEPLOY_TARGET=vercel 或 DEPLOY_TARGET=cloudflare）。
将商店前端部署到 Vercel 通常是首选方案，原因如下：
- 解决 Cloudflare Error 1042（Worker 间通信阻塞）： 当
cod-server部署在免费*.workers.dev子域名且没有自定义域名时，Cloudflare 会阻止另一个位于*.workers.dev的 Cloudflare Worker 获取它。Vercel 运行在 Cloudflare 内部网络之外，允许商店前端在无需自定义域名的情况下获取*.workers.dev上的cod-server。 - 慷慨的全球边缘带宽： Vercel 为商店前端流量提供慷慨的带宽和边缘 CDN 缓存。
- 自动预览部署： 每个 Git 分支/PR 都可以拥有自己的预览 URL，用于测试主题更改。
必需的环境变量
在部署之前，请收集以下值：
| 变量 | 描述 | 示例 |
|---|---|---|
DEPLOY_TARGET | 必填。 告知 astro.config.mjs 使用 @astrojs/vercel | vercel |
COD_SERVER_URL | 必填。 已部署的 cod-server API 的基础 URL | https://api.yourdomain.com 或 https://codflow-server.<account>.workers.dev |
STORE_API_KEY | 必填。 与 D1 中已种子的密钥匹配的原始商店 API 密钥 | 在 codflow-setup 步骤 4 中生成 |
MEDIA_DOMAIN | 可选。 用于 R2 图片 CDN 的自定义域名 | media.yourdomain.com |
[!IMPORTANT]
STORE_API_KEY是机密。它在服务器端 SSR 路由和 API 代理中使用。切勿在客户端包中暴露它。
部署方法
选择**方法 1（Vercel CLI）进行自动化/终端部署，或方法 2（Vercel 控制台 / Git）**从 GitHub 进行持续部署。
方法 1：通过 Vercel CLI 部署（推荐用于 AI 代理）
1. 先决条件
- 确保 Vercel CLI 可通过
npx vercel访问（或已全局安装）。 - 检查身份验证：
npx vercel whoami- 如果浏览器可用：
npx vercel login - 如果无头/CI 环境：在环境中设置
VERCEL_TOKEN（export VERCEL_TOKEN="<token>"）。
- 如果浏览器可用：
2. 配置并链接项目
导航到商店前端目录：
cd cod-astro/theme01
运行初始设置：
npx vercel link
按照交互式提示操作（或在非交互式会话中提供标志）：
- 链接到现有项目？
No（如果是链接现有项目则选Yes） - 项目名称：
<project>-storefront（例如mystore-storefront） - 您的代码位于哪个目录？
./
3. 设置环境变量
使用 CLI 添加所需的生产环境变量：
# 1. 部署目标
printf "vercel" | npx vercel env add DEPLOY_TARGET production
# 2. 后端 API URL（必须以 https:// 开头）
printf "https://<your-cod-server-domain>" | npx vercel env add COD_SERVER_URL production
# 3. 商店 API 密钥
printf "<your-raw-store-api-key>" | npx vercel env add STORE_API_KEY production
# 4. 可选：媒体域名（如果配置了 R2 自定义域名）
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production
（可选：如果您打算使用预览分支，也可以将它们添加到 preview 和 development 环境中。）
4. 构建并部署到生产环境
使用 Vercel 适配器执行生产部署：
cd cod-astro/theme01
npx vercel --prod
Vercel 将上传项目，执行 npm run build:vercel（或 DEPLOY_TARGET=vercel 下的 astro build），编译 SSR 无服务器/边缘函数，并提供实时生产 URL（例如 https://<project>-storefront.vercel.app）。
方法 2：通过 Vercel 控制台部署（Git 集成）
在链接 GitHub/GitLab/Bitbucket 仓库时使用此方法：
-
在 Vercel 中导入仓库：
- 在 Vercel 控制台中，点击 Add New... → Project。
- 选择
codflow-os仓库。
-
配置项目设置：
- 项目名称： 例如
codflow-storefront - 框架预设：
Astro - 根目录： 点击 Edit 并选择
cod-astro/theme01。勾选 "Include source files outside of the Root Directory in the Build Step" 选项（这是必需的，因为工作区依赖项会解析到根目录的node_modules）。 - 构建命令： 切换 Override 并设置：
（或者，如果在环境变量中设置了npm run build:vercelDEPLOY_TARGET=vercel，则保留默认的astro build）。 - 输出目录： 保留默认值（
.vercel/output）。 - 安装命令： 保留默认值（
npm install/ 根工作区安装）。
- 项目名称： 例如
-
配置环境变量： 在 Environment Variables 下，添加：
DEPLOY_TARGET=vercelCOD_SERVER_URL=https://<your-cod-server-domain>STORE_API_KEY=<your-raw-store-api-key>MEDIA_DOMAIN=<media.yourdomain.com>（可选）
-
部署：
- 点击 Deploy。Vercel 将构建工作区，使用
@astrojs/vercel打包 Astro 站点，并分配一个生产 URL。
- 点击 Deploy。Vercel 将构建工作区，使用
验证与烟雾测试
部署完成后，针对实时 Vercel URL 运行以下检查：
| 目标 | 测试命令/操作 | 预期结果 |
|---|---|---|
| 首页 | curl -s -o /dev/null -w "%{http_code}" https://<storefront-url> | 200（HTML 响应） |
| 分类 SSR | 在浏览器中打开 https://<storefront-url>/ | 产品加载，包含图片、价格和标题 |
| 产品详情 | 在浏览器中打开 https://<storefront-url>/product/<slug> | 产品页面渲染，包含结账/订单表单 |
| 购物车/订单流程 | 提交测试订单（或测试模态框） | 订单注册成功，显示感谢页面 |
通过终端测试：
# 验证首页返回 200 OK
curl -s -I "https://<your-storefront>.vercel.app" | head -n 5
# 通过商店前端代理验证 API 连接
curl -s "https://<your-storefront>.vercel.app/api/cart/validate" \
-H "Content-Type: application/json" \
-d '{"items":[]}'
# 期望返回有效的 JSON 响应
自定义域名设置
要为 Vercel 商店前端附加自定义域名：
- 在 Vercel 控制台中：项目 → Settings → Domains。
- 输入您的域名（例如
store.yourdomain.com或yourdomain.com）。 - 配置 DNS 记录：
- 对于子域名（
store.yourdomain.com）：添加指向cname.vercel-dns.com的CNAME记录。 - 对于根域名（
yourdomain.com）：添加指向76.76.21.21的A记录。
- 对于子域名（
- 等待 SSL 证书签发（通过 Let's Encrypt 自动完成）。
故障排除
| 问题 | 原因 | 解决方案 |
|---|---|---|
构建失败：Cannot find module '@astrojs/vercel' | cod-astro/theme01 中缺少依赖 | 在仓库根目录运行 npm install @astrojs/vercel --workspace=cod-astro-theme01。 |
| 构建输出的是 Cloudflare 输出而不是 Vercel 输出 | DEPLOY_TARGET 未设置为 vercel | 确保 Vercel 环境变量中存在 DEPLOY_TARGET=vercel，或运行 npm run build:vercel。 |
| 商店前端加载但显示空白产品/错误横幅 | COD_SERVER_URL 不正确或无法访问 | 确认 COD_SERVER_URL 以 https:// 开头且与实时 API Worker 匹配。验证 curl https://<api-url>/api/docs 返回 200。 |
| 订单失败并返回 401 Unauthorized | STORE_API_KEY 不匹配 | Vercel 中 STORE_API_KEY 的值必须与 codflow-setup 步骤 5 中种子到 D1 数据库的密钥匹配。请重新检查或更新 Vercel 中的密钥。 |
| Monorepo 构建无法解析共享包 | Vercel 根目录配置 | 如果使用 Git 集成，请确保在 Vercel 项目设置中启用 "Include source files outside of the Root Directory"，或在 cod-astro/theme01 内部通过 npx vercel 部署。 |
Node.js 版本警告：Node.js 26 is not supported | Vercel 无服务器函数最高支持 Node 24 | 在 Node 26 开发机器上是正常警告；Vercel 在其云函数中自动运行 Node 24。 |
| 图片无法从 R2 加载 | MEDIA_DOMAIN 配置错误或缺少 CORS | 验证 MEDIA_DOMAIN 已设置（仅主机名，不带 https://）。确保 R2 存储桶 CORS 策略允许来自 Vercel 域名的请求。 |