ray-launch

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   # 直接说目标

开跑前先定位三件事(用户没说就问,别假设):

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 身份(形如 [e-mail]),而不是全局那个个人邮箱。上 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 是一个站的实战沉淀,不是通用真理。遇到和源料冲突的新情况,以"为什么"为准去推,别硬套条目。