Take a site that is already written from "the code runs" to "it really works online, can be found, has data flowing, and can be handed over". This is not a deployment tutorial - it is a launch checklist that has been through pitfalls, and each pitfall clearly points outwhy it is a pitfall, so you understand instead of copying.
What scenarios this checklist has been hammered in: the complete launch of a foreign trade manufacturing B2B inquiry site. It went through the full stack of Next 14 + Vercel + headless WordPress, then because "the client wants to maintain content themselves", the entire set of designs was replicated and migrated back to WP + visual editor, and finally the domain was switched from Vercel back to the CMS host. Every pitfall below has a real corpse - not an assumption from a tutorial, but something stepped on at the launch site.
Usage
/ray-launch ~/projects/apps/mysite # 给项目路径,自动判路线走全流程
/ray-launch 一个单页落地页 # 描述站点类型也行
/ray-launch 帮我把 Next 站上线到 Vercel # 直接说目标
Before starting, first pin down three things (if the user did not say, ask; do not assume):
- Who maintains the content long term?- developer / client themselves. This is the main axis of selection, not technical advancement.
- Does this site have content that changes frequently?(products, prices, copy) - determines whether a CMS is needed.
- Launch target domain + where it is currently hosted- determines whether domain switching is needed, and who holds the email MX.
Layer one: selection fork (judge the route first, then go through the checklist)
The checklists for the three routes are completely different. Taking the wrong route is like putting the shackles of a full stack on a single-page site. Judge according to the table below; after judging, read only the corresponding reference.
| Route | What it looks like | When to choose it | Which one to read |
|---|---|---|---|
| Pure static | Single/several index.html, no build, no framework, no config, host directly |
Landing page / marketing single page / very little content and almost never changed | references/static.md |
| headless + frontend | Next (Vercel) as the frontend + WordPress/CMS as a pure content backend, API/GraphQL data fetching, ISR incremental updates | Fits the existing frontend stack, wants SSG/ISR for SEO,developer maintains content | references/headless.md |
| Full stack (rendered inside CMS) | Both content and rendering are in the CMS (such as WP + visual editor) | The client wants WYSIWYG and to change it themselves, a typical form for B2B inquiry sites | references/headless.md migration section |
The decision axis = who maintains it long term, not which technology is more advanced. The biggest firsthand lesson on this route: a self-developed Next frontend is technically cleaner, but if the client changes one sentence of copy, they have to touch CMS fields; a visual editor is WYSIWYG, and the client can change it themselves. In the end, for "client self-maintenance ability > developer's stack preference", the headless version that had already gone live wasreplicated and migrated back in its entirety to rendering inside the CMS. If the selection is wrong, the smoother the launch, the more painful it will be later.
Principle of proportionAnything clients will change frequently (text/images/numbers/products) should be made into native fields/visual components; only purely decorative, structurally complex, and client-never-touched things (process connector lines, certification walls) should be hardcoded as HTML blocks. Hardcoding something the client wants to change is leaving yourself a maintenance IOU.
Layer 2: The main launch process (six-step skeleton)
Once the route is chosen, follow this main line. The detailed checklist for each step is in the corresponding reference; the main text only gives the skeleton and decision points.
1 选型定案 → 2 部署上架 → 3 数据流打通 → 4 上线前自查 → 5 域名切换 → 6 上线后验证 + 交接
- Pure static: 1 → 2 → 4 → 6, skip 3 (there is no data flow) and 5 (unless you need to switch domains). Don't force in the CMS step.
- headless/full-stack: all six steps. Data flow (3) and domain switching (5) are the two high-risk areas on this route.
Complete pitfalls for steps 2/3 → read references/headless.md or references/static.md.
Steps 5/6 (domain switching + post-launch verification) are the hardest part → read references/switch-runbook.md.
For the deliverable of step 6 → read references/handoff.md。
Silent failure pitfalls wall (the number-one killer at launch)
The most dangerous thing at launch is not an error—errors you can see. It'ssilent failure: it doesn't report an error, the page looks normal, but things are broken. Every item below has actually bitten someone; self-check them one by one:
① Vercel deployment: the git commit author email must be the GitHub identity connected to Vercel.
Vercel matches the connected GitHub account by the commit author email to attribute/authorize deployments. If the author email is not that identity, after you push,the deployment simply does not trigger and does not report an error—you think you shipped, but production is still the old version. Countermeasure: override the local git identity separately for this repo, using GitHub's noreply identity (in the form 12345678+you@users.noreply.github.com), rather than the global personal email. For repositories on Vercel, git config user.email you must verify. See references/headless.md。
② ISR mock fallback will silently fall back. Robust design: any WP/CMS fetch failure (non-200 / GraphQL error / network exception) falls back to mock data, and the frontend does not go blank. The cost:if a field name is changed / the backend goes down, what the frontend "still displays" is actually mock, not real data, and it is extremely hard to notice with the naked eye. During construction, don't mess with the GraphQL/field structure; to verify that real data is connected, look at a specific piece of real content, not just "there is something on the page."
③ CDN/static caching creates the illusion that "the fix didn't work."
The host/CDN caches old CSS/JS/HTML. Fetching the bare URL gets the old file, and you think "the change didn't take effect" and waste effort. Always verify with a random query parameter (?v=$(date +%s)) to bypass the cache; only then are you getting the real current version.
④ Form demo mode silently sends no email. Forms often have a design where "if no mail service is configured, it enters demo mode": the submission succeeds, returns ok, butonly logs on the server side, and not a single email is sent. Before launch, you must actually configure the email-sending key andactually test receiving one email, don't trust the green checkmark of "submitted successfully." A pitfall actually tested: MX often lands at an enterprise email provider, not the host, so the sending channel must target where the real mailbox actually lands.
⑤ After switching, the old domain remains in the page source.
After a headless/CMS migration, absolute URLs of the old domain (cms. subdomain) are everywhere in the database and rendering. After switching, View Source and search for the old domainmust be 0, otherwise production is still secretly requesting the old backend. This is a must-check item in the switching runbook.
Pre-launch self-check (before switching/publishing)
Before sending it out, go through it once in front of yourself (the detailed checklist is in references/switch-runbook.md section T-2):
- Are all the environment variables configured on the hosting platform? (sending key, CMS endpoint, recipient email) — local
.envwill not automatically go to the cloud - Lower the TTL of the domain DNS in advance (e.g. 300s) to leave room for rollback to take effect quickly
- Be clear about the email-related DNS records (MX / SPF / DKIM),do not touch a single one during the switch— touch them and the client won't receive inquiries, which is worse than the site going down
- If there is a content backend, do a baseline backup first; agree on a switch time window (choose the target client's off-peak hours)
Post-launch verification (go through it once on a real device, don't trust the console's green light)
Verify item by item immediately after the switch/publish (the full version is in references/switch-runbook.md section T-Day/T+14):
- Homepage + every key page returns 200 on a real device, no sections missing
- View Source search for the old domain = 0(see pit wall ⑤)
- Form submission → the real inbox actually receives one(see pit wall ④) — this is the lifeline of a B2B site; missing one inquiry is losing money
- sitemap.xml is normal and uses the new domain → submit it to Google Search Console
- 301 the old domain/subdomain to the new domain (to catch old backlinks)
- SSL has no mixed content warnings; spot-check 2 pages on mobile
- Observation period (T+1~T+14): watch GSC indexing and 404s, add 301s for high-frequency 404s.Cleanup actions (deleting plugins, retiring fields, revoking keys) should all be put off until after the observation period ends— preserving the rollback path is more important than wrapping up early
Handover (the wrap-up of a B2B site, not optional)
The site going live does not mean the work is done. The client needs to be able to maintain it themselves, otherwise they'll come to you every time they change a single word. Handover deliverables and permission design → read references/handoff.md(green/yellow/red three-zone mental model + dual-channel inquiry anti-leak + restricted editor role).
Discipline
- For each pit, explain why first, then how to handle it— only when users understand the mechanism can they save themselves on variants you didn't foresee, instead of copying something that no longer works.
- Silent failures are caught by active verification, not by waiting for errors: add a query to bypass the cache, look at the real content rather than "the page has something", actually send an email, View Source to search for leftovers.
- A switch always comes with a rollback: if any step goes wrong, changing DNS back + rebinding the platform restores it; cleanup actions are deferred to preserve this path.
- Choose based on the maintainer: whether launch goes smoothly is temporary, but who will modify it long-term is for life. If unsure, ask "who will change this place three months from now".
- This checklist is the practical accumulation of one site, not a universal truth. When you encounter new situations that conflict with the source material, reason based on the "why", don't rigidly apply the items.