| name | ray-launch |
| description | 把一个已经写好的落地页 / 官网 / B2B 询盘站从"代码就绪"带到"线上可访问、SEO 就绪、数据流通、可交接"。先按"谁长期维护"选技术路线(纯静态 / headless CMS+前端 / 全栈),再走一份带真实静默失败坑位的上线 checklist:Vercel 部署、域名 DNS 切换、ISR/revalidate 数据流、SEO metadata、表单询盘链路,直到真机验证通过并交接给客户。当用户要把站上线、部署 Next 到 Vercel、接 headless WordPress/CMS、做上线前检查、切换域名、或问"这个站能不能发了"时使用。触发:/ray-launch 「项目路径或站点类型」。不用于:本地开发调试与写业务代码、纯后端服务/API 部署(那更接近 /ray-vpsinit)、内容创作或选题。 |
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 # 直接说目标
开跑前先定位三件事(用户没说就问,别假设):
- 谁长期维护内容?——开发者 / 客户自己。这是选型主轴,不是技术先进性。
- 这站有没有会频繁变的内容?(产品、价格、文案)——决定要不要 CMS。
- 上线目标域名 + 现在托管在哪——决定要不要做域名切换,以及邮箱 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 是一个站的实战沉淀,不是通用真理。遇到和源料冲突的新情况,以"为什么"为准去推,别硬套条目。
