# Ray Launch

> 把一个已经写好的落地页 / 官网 / B2B 询盘站从"代码就绪"带到"线上可访问、SEO 就绪、数据流通、可交接"。先按"谁长期维护"选技术路线(纯静态 / headless CMS+前端 / 全栈),再走一份带真实静默失败坑位的上线 checklist:Vercel 部署、域名 DNS 切换、ISR/revalidate 数据流、SEO metadata、表单询盘链路,直到真机验证通过并交接给客户。当用户要把站上线、部署 Next 到 Vercel、接 headless WordPress/CMS、做上线前检查、切换域名、或问"这个站能不能发了"时使用。触发:/ray-launch 「项目路径或站点类型」。不用于:本地开发调试与写业务代码、纯后端服务/API 部署(那更接近 /ray-vps)、内容创作或选题。

- Skill: `imraywang/ray-launch` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add imraywang/ray-launch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/imraywang/ray-launch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: imraywang (https://skillmd.com/u/imraywang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/imraywang/ray-launch

---


# ray-launch:落地页 / B2B 站上线全流程

把一个已经写好的站,从"代码能跑"带到"线上真能用、搜得到、数据通、能交接"。这不是部署教程——是一份踩过坑的上线 checklist,每个坑都点明**为什么会坑**,让你理解而不是照抄。

**这份 checklist 在什么场景锤过**:一个外贸制造业 B2B 询盘站的完整上线。走过 Next 14 + Vercel + headless WordPress 全栈,又因为"客户要自己维护内容"把整套设计复刻迁回 WP + 可视化编辑器,最后把域名从 Vercel 切回 CMS 主机。下面每一条坑都有一具真实的尸体——不是教程里的假设,是上线现场踩出来的。

## 用法

```
/ray-launch ~/projects/apps/mysite       # 给项目路径,自动判路线走全流程
/ray-launch 一个单页落地页                # 描述站点类型也行
/ray-launch 帮我把 Next 站上线到 Vercel   # 直接说目标
```

开跑前先定位三件事(用户没说就问,别假设):
1. **谁长期维护内容?**——开发者 / 客户自己。这是选型主轴,不是技术先进性。
2. **这站有没有会频繁变的内容?**(产品、价格、文案)——决定要不要 CMS。
3. **上线目标域名 + 现在托管在哪**——决定要不要做域名切换,以及邮箱 MX 在谁那里。

## 第一层:选型分叉(先判路线,再走 checklist)

**三条路线的 checklist 完全不同,走错路线等于给单页站套上全栈的枷锁。** 按下表判,判完只读对应那一份 reference。

| 路线 | 长什么样 | 什么时候选 | 读哪份 |
|---|---|---|---|
| **纯静态** | 单个/几个 `index.html`,无 build、无框架、无 config,直接托管 | 落地页 / 营销单页 / 内容极少几乎不改 | `references/static.md` |
| **headless + 前端** | Next(Vercel)当前台 + WordPress/CMS 当纯内容后台,API/GraphQL 取数,ISR 增量更新 | 贴现有前端栈、要 SSG/ISR 利于 SEO、**开发者维护内容** | `references/headless.md` |
| **全栈(CMS 内渲染)** | 内容和渲染都在 CMS 里(如 WP + 可视化编辑器) | **客户要所见即所得自己改**、B2B 询盘站典型形态 | `references/headless.md` 的迁移段 |

**决策轴 = 谁长期维护,不是哪个技术更先进。** 这条路上最大的一手教训:自研 Next 前端技术上更干净,但客户改一句文案要动 CMS 字段;可视化编辑器所见即所得,客户自己能改。最后为了"客户自维护能力 > 开发者的栈偏好",把上过线的 headless 版**整套复刻迁回** CMS 内渲染。选型选错,上线越顺后面越痛。

**分寸原则**:客户会高频改的(文字/图片/数字/产品)一律做成原生字段/可视化组件;纯装饰性、结构复杂、客户永不碰的(工艺连接线、认证墙)才写死成 HTML 块。写死一处客户想改的东西,就是给自己埋一张维护欠条。

## 第二层:上线主流程(六步骨架)

选完路线,按这条主线走。每步的详细清单在对应 reference,正文只给骨架和判断点。

```
1 选型定案 → 2 部署上架 → 3 数据流打通 → 4 上线前自查 → 5 域名切换 → 6 上线后验证 + 交接
```

- **纯静态**:1 → 2 → 4 → 6,跳过 3(没有数据流)和 5(除非要切域名)。别硬塞 CMS 步骤。
- **headless/全栈**:六步全走。数据流(3)和域名切换(5)是这条路的两个高危区。

第 2/3 步的完整坑位 → 读 `references/headless.md` 或 `references/static.md`。
第 5/6 步(域名切换 + 上线后验证)是最硬的一段 → 读 `references/switch-runbook.md`。
第 6 步的交接物 → 读 `references/handoff.md`。

## 静默失败坑位墙(上线的头号杀手)

上线最危险的不是报错——报错你看得见。是**静默失败**:它不报错、页面看着正常,但东西是坏的。下面每一条都真实咬过人,逐条自查:

**① Vercel 部署:git commit 作者邮箱必须是 Vercel 连接的那个 GitHub 身份。**
Vercel 按 commit 作者邮箱匹配已连接的 GitHub 账号来归属/授权部署。作者邮箱若不是那个身份,push 上去**部署根本不触发,也不报错**——你以为发了,线上还是旧的。对策:给这个 repo 单独覆写本地 git 身份,用 GitHub 的 noreply 身份(形如 `12345678+you@users.noreply.github.com`),而不是全局那个个人邮箱。上 Vercel 的仓库 `git config user.email` 一定要核对。详见 `references/headless.md`。

**② ISR mock 兜底会静默回落。**
健壮设计:WP/CMS 取数任何失败(非 200 / GraphQL 报错 / 网络异常)都回落 mock 数据,前端不白屏。代价:**改了字段名 / 后台挂了,前端"照样显示"的其实是 mock,不是真数据**,肉眼极难发现。施工期别乱动 GraphQL/字段结构;验证真数据接通要看具体某条真实内容,不能只看"页面有东西"。

**③ CDN/静态缓存造成"修复无效"假象。**
主机商 / CDN 会缓存旧 CSS/JS/HTML。裸 URL 拉到的是旧文件,你会以为"改了没生效"而白折腾。验证一律带随机 query 参数(`?v=$(date +%s)`)绕缓存,拿到的才是真的当前版本。

**④ 表单 demo 模式静默不发信。**
表单常有"未配邮件服务就进 demo 模式"的设计:提交成功、返回 ok、但**只在 server 端 log,一封信都没发**。上线前必须真配好发信密钥并**实测收到一封**,别信"提交成功"的绿勾。实测过的坑:MX 常落在企业邮箱服务商、不在主机商,发信通道要对准真实邮箱落地的地方。

**⑤ 切换后旧域名残留在页面源码里。**
headless/CMS 迁移后,数据库和渲染里到处是旧域名(`cms.` 子域)的绝对 URL。切换后 View Source 搜旧域名**必须为 0**,否则线上还在偷偷请求旧后台。这是切换 runbook 里的必查项。

## 上线前自查(切换/发布之前)

发出去之前,当着自己的面过一遍(详细清单在 `references/switch-runbook.md` 的 T-2 段):

- 环境变量在托管平台配全了吗?(发信密钥、CMS endpoint、收件邮箱)——本地 `.env` 不会自动上云
- 域名 DNS 的 TTL 提前调低(如 300s),给回滚留快速生效的余地
- 邮箱相关的 DNS 记录(MX / SPF / DKIM)心里有数、**切换时一个都不许动**——动了客户收不到询盘,比站挂还严重
- 有内容后台的,先做一次基线备份;约好切换时间窗(选目标客户的低峰时段)

## 上线后验证(真机过一遍,别信控制台绿灯)

切换/发布后立刻逐项验(完整版在 `references/switch-runbook.md` 的 T-Day/T+14 段):

- 首页 + 每个关键页真机访问返回 200,板块不缺
- **View Source 搜旧域名 = 0**(见坑位墙⑤)
- **表单提交 → 真实收件箱真的收到一封**(见坑位墙④)—— 这是 B2B 站的命根子,询盘漏一单就是漏钱
- sitemap.xml 正常且是新域名 → 提交给 Google Search Console
- 旧域名/子域 301 到新域名(旧外链兜底)
- SSL 无混合内容告警;移动端抽查 2 页
- 观察期(T+1~T+14):盯 GSC 收录与 404,高频 404 补 301。**清理动作(删插件、退役字段、撤密钥)一律放到观察期结束后**——保住回滚路径比早点收尾重要

## 交接(B2B 站的收尾,不是可选项)

站上线不等于活干完。客户要能自己维护,否则每改一个字都来找你。交接物和权限设计 → 读 `references/handoff.md`(绿/黄/红三区心智模型 + 询盘双通道防漏单 + 受限编辑角色)。

## 纪律

- **每个坑先讲为什么再讲怎么办**——用户理解了机制,才能在你没预见到的变体上自救,而不是照抄失效。
- **静默失败靠主动验证抓,不靠等报错**:带 query 绕缓存、看真实内容而非"页面有东西"、真发一封信、View Source 搜残留。
- **切换永远配回滚**:任何一步异常,DNS 改回 + 平台重绑即恢复;清理动作后置以保住这条路。
- **选型以维护者为轴**:上线顺不顺是一阵子,谁来长期改是一辈子。拿不准就问"三个月后谁改这里"。
- 这份 checklist 是一个站的实战沉淀,不是通用真理。遇到和源料冲突的新情况,以"为什么"为准去推,别硬套条目。