把一个静态站扔上 CloudBase 的完整路径

一个"个人主页"而已,理应半小时搞定。但 MCP 设备码、manageHosting 三个静默坑、再到 setWebsiteDocument,任何一步没按规矩走,都会得到一个 LatestStatus: "RUNNING" 的假象 — 页面其实根本没渲染。

这篇是"我已经撞过的墙"清单,按时间顺序写下来 — 留给自己,也留给下次忘记的人。

1. MCP 设备码登录

CloudBase 的 MCP 不接受裸 SecretId/SecretKey,走的是 device-code flow。每台机器第一次都要来一次:

npx -y mcporter call cloudbase auth \
  --args '{"action":"start_auth","authMode":"device"}'
# → 返回 user_code + verification_uri
# 用户在浏览器打开 URI、敲入 code、确认

确认完继续调 action=status 轮询,直到 auth_status:"READY" 且 env_setup_status:"AUTO_BOUND"。不要重发 start_auth — 每次都生成新 code,旧的立即作废。

2. 纯静态站不要用 manageApps(deployApp)

manageApps(deployApp, framework: "static") 内部跑的是 npm install && npm run build && tcb hosting deploy . /。如果你的项目根本没有 package.json,这一步会静默失败:状态从 BUILDING 跳到 FAILED,getBuildLog 因为 buildId int64 跟 schema 申明的 string 对不上,直接拒绝。

纯静态 HTML,老老实实用 manageHosting。别和构建工具打架。

3. manageHosting(upload) 的三个坑

npx -y mcporter call cloudbase manageHosting \
  --args '{"action":"upload","localPath":"/path/to/dir","cloudPath":"/"}'

npx -y mcporter call cloudbase manageHosting \
  --args '{"action":"setWebsiteDocument",
           "indexDocument":"index.html",
           "errorDocument":"index.html"}'

三条 landmines:

① localPath 必须是目录,不能传 zip。
② cloudPath 是前缀,不是文件名 — 传 "index.html" 会让所有文件落到 index.html/styles.css。
③ 最终 URL 是 https://<envId>-<appid>.tcloudbaseapp.com/,不是 <envId>.tcloudbaseapp.com/。

4. 自检:不要信 LatestStatus

部署完,不要信 LatestStatus: "RUNNING"。在同一个终端里跑:

URL="https://<envId>-<appid>.tcloudbaseapp.com/"
curl -s -o /dev/null -w "%{http_code}\n" "$URL"   # → 200
curl -s "$URL" | grep -i "<title>"               # → 看到你的标题

再到浏览器里检查 document.querySelectorAll('.essay').length > 0、控制台没有 uncaught。

页面真的能看见,才算 done。"RUNNING" 是流水线不报错,不是页面真的渲染了。