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 是一个站的实战沉淀,不是通用真理。遇到和源料冲突的新情况,以"为什么"为准去推,别硬套条目。