# 在用户自己的 Vercel / Cloudflare 上部署

> 这份文档教**你(AI)**怎么用**用户自己的账号**把站部署出去。
>
> **搭台不参与部署。** 它不发凭据、不代部署、不碰用户的云账号。
> 部署是你和用户的事;搭台只负责给域名和之后的服务。
>
> 之所以写这份文档:会用 AI 的人**卡住的地方不是写代码,是让代码上线**。
> 这一段没人教过你,所以你会在这一步开始问用户问题 —— 而用户答不上来。
> 读完这份,你就不需要问了。

---

## 最重要的一条:用浏览器登录,不要让用户手抄 token

小白**不会**去 `vercel.com/account/tokens` 建一个 token 再粘给你。
那个页面本身就会把他劝退。

正确做法是让用户跑一条命令,在浏览器里点一下:

```bash
vercel login      # 打开浏览器,点一次授权
wrangler login    # 同上
```

凭据会落到用户本机(`~/.vercel/`、`~/.wrangler/`),之后你所有命令自动带上。

**你该怎么跟用户说**:「我要在浏览器里打开一个授权页面,你点一下同意就行。」
这是一句**陈述**,不是提问。用户不需要理解任何东西。

只有当用户明确在做 CI、或者环境没法开浏览器时,才退回
`VERCEL_TOKEN` / `CLOUDFLARE_API_TOKEN` 环境变量这条路。

---

## 通用顺序

严格按这个顺序,不要跳步:

```
1. 搭台 reserve          → 拿到 hostname 和 verify_token
2. 写验证文件            → public/.well-known/datai-verify,内容就是 verify_token
3. 登录                  → vercel login / wrangler login
4. 部署
5. 自检部署真的通了       ← 最容易跳过、也最容易出事的一步
6. 搭台 bind             → 上线
```

第 1 步必须在第 2 步之前 —— 没有域名就不知道 `NEXT_PUBLIC_SITE_URL` 填什么。

---

## Vercel

### 建项目并部署

```bash
vercel link --yes                          # 关联/创建项目,项目名决定默认域名
vercel deploy --prod --yes                 # ← 必须带 --prod
```

**`--prod` 不能省。** 不带它得到的是一个**每次部署都变**的预览地址
(`my-shop-abc123.vercel.app`)—— 你今天绑上去,明天重新部署就失效了。

生产域名是稳定的:`<项目名>.vercel.app`。

### 环境变量

如果站点要读 `NEXT_PUBLIC_SITE_URL` 这类变量:

```bash
vercel env add NEXT_PUBLIC_SITE_URL production
# 粘贴 https://huadian.webdatai.top

vercel deploy --prod --yes      # ← 加完变量必须重新部署,否则不生效
```

**顺序坑**:先设变量再部署。反过来会得到一堆 `undefined`。

### 拿到 target

生产域名就是:

```
<项目名>.vercel.app
```

不要复制完整的 deployment URL(那串带 hash 的),**只要项目级的域名**。

### Vercel 上最容易踩的三个坑

| 坑 | 症状 | 做法 |
|---|---|---|
| **部署保护开着** | 平台去验证时被挡在登录页 | 项目 Settings → Deployment Protection 关掉。**开着的话搭台的验证请求会拿到 401** |
| **只跑了 `vercel deploy`** | 拿到的是预览地址,明天就变 | 加 `--prod` |
| **验证文件没进构建产物** | bind 报 `TARGET_NOT_VERIFIED` | 放到 `public/`,不是项目根目录 |

---

## Cloudflare Workers

### 部署

```bash
# wrangler.toml 里至少有 name 和 main
wrangler deploy
```

部署成功后会输出一个地址:

```
https://<worker 名>.<你的账号子域>.workers.dev
```

**那串就是 target。**

### workers.dev 子域必须开着

每个 Cloudflare 账号有一个 `*.workers.dev` 子域,**默认是开的**,
但可能被手动关掉过。

如果部署完拿不到地址,让用户去 Workers 面板确认
「Your subdomain」是启用状态。这个开关**一个账号只设一次**。

### R2(如果站点要存文件)

```bash
wrangler r2 bucket create my-shop-uploads
```

R2 不需要域名 —— 通过 API 访问即可。只有当用户想**公开直链图片**时才需要绑域名,
那时再回来看搭台的自定义域名服务。

### Workers 上最容易踩的坑

| 坑 | 症状 | 做法 |
|---|---|---|
| **忘了 `wrangler login`** | `wrangler deploy` 报认证失败 | 先登录 |
| **workers.dev 子域被关** | 部署成功但拿不到地址 | 面板里打开 |
| **`wrangler.toml` 缺 `main`** | 找不到入口 | 补上入口文件路径 |
| **验证文件不在静态产物里** | bind 报 `TARGET_NOT_VERIFIED` | 确认它被 Worker 返回,而不是躺在仓库里 |

---

## 第 5 步:自检(必做,不要跳)

**在调 bind 之前**,自己确认部署真的通了:

```bash
curl -sS -o /dev/null -w '%{http_code}\n' https://<target>/
curl -sS https://<target>/.well-known/datai-verify
```

期望:

- 第一条返回 `200` —— 站点活着
- 第二条**原样返回 verify_token** —— 验证文件到位了

两条都对了再 bind。不对就修部署,不要去调 bind ——
bind 的报错只会告诉你"没找到",不会告诉你为什么没找到。

### 特殊情况:部署保护

如果第一条返回 `401` 或 `403` 而不是 `200`,大概率是 Vercel 的部署保护开着。
去项目 Settings 关掉它。

**这一步你完全可以自己判断出来**,不需要问用户。

---

## 常见错配(对着查)

| 你看到的 | 真正的原因 |
|---|---|
| bind 报 `TARGET_NOT_REACHABLE` | 站点在公网打不开 —— 部署没完成,或被部署保护挡着 |
| bind 报 `TARGET_NOT_VERIFIED` | 站点开着,但验证文件缺失或内容不对 |
| verify 文件返回了 HTML | 那是 404 页面 —— 你的文件没进构建产物 |
| target 带了一串 hash | 你复制了 deployment URL,不是项目域名 |
| 重新部署后绑不上了 | 大概率用了预览地址,地址变了 |

---

## 不要做的事

| 不要 | 为什么 |
|---|---|
| 让用户去网页后台手抄 token | 小白做不到,这一步会把整个流程卡死 |
| 用预览地址当 target | 每次部署都变,站会莫名其妙失效 |
| 跳过第 5 步自检直接 bind | bind 的报错不会告诉你部署哪里坏了 |
| 把用户云账号的凭据发给搭台 | 搭台不接受,也永远不该接受 |
| 反复重试 bind | 先按上面的表定位,再改,再试 |