部署網站
將 Next.js 行銷網站 (web/site/) 部署到 Vercel 正式環境,但將其視為一個目標,而非單一指令:將所有網站相關的修正合併到 main 分支、部署它、證明它在所有頁面和電子郵件擷取流程(桌面與行動裝置)的正式環境中都能運作,並持續修正與重新部署,直到一切都綠燈通過。
目標合約
將此技能當作一個閉環來執行。請勿僅憑 Vercel 部署成功就宣告任務完成;一個部署可能成功,但某個頁面卻回傳 500 錯誤、行動裝置版型跑掉,或 waitlist 寫入無聲地失敗。
- 完成 (DONE) 當:所有網站相關的修正都已提交並推送到
main、正式環境部署成功、以下每個路由在桌面 與 行動裝置上都回傳 200 且正確渲染(無控制台/網路錯誤),而且電子郵件擷取流程能接受提交並持續儲存(透過管理員讀取驗證),且不留任何測試資料。 - 未完成 (NOT DONE,再次循環) 當:任何一個路由無法渲染、在某個 viewport 下版型跑掉、控制台出現錯誤,或電子郵件擷取無法完整來回。請修正來源碼,重新合併、重新部署、重新驗證。
- 受阻 (BLOCKED,停止並回報) 當:修正需要你沒有的憑證或決策(例如 KV 儲存服務掛掉、管理員 token 遺失、Vercel 認證過期),或者同一個失敗在 3 次修正嘗試後依然存在。請回報確切的失敗原因與你嘗試過的方法;不要無限循環。
保留每次迭代的簡短執行記錄(失敗內容、你修改了什麼、重新驗證的結果),以便循環過程可供審計。如果使用者希望將其設為持續性的 /goal,請將目標指向此技能並使用相同的 DONE/BLOCKED 條件。
循環
階段 0 範圍界定與合併 收集網站修正 -> 本地驗證 -> 提交 -> 推送到 main
階段 1 部署 建置 -> npx vercel@latest --prod (從儲存庫根目錄)
階段 2 驗證 (正式環境) 工作流程擴散:路由 x viewports + 電子郵件擷取
階段 3 分類 有任何紅燈?修正來源碼 -> 回到階段 0
全部綠燈?-> DONE
背景資訊
- 專案:Vercel 上的
opentraces(scopejayfareis-projects) - 框架:Next.js 16 (App Router)
- 根目錄:Vercel 設定根目錄為
web/site/ - 網域:opentraces.ai(正式環境:https://opentraces.ai)
- 建置:
next build(從web/site/執行) - 版本:在建置時經由
next.config.ts從src/opentraces/__init__.py自動讀取 - 電子郵件擷取:
EarlyAccessForm將資料 POST 到/api/waitlist(正式環境使用 Upstash/KV)。在/(透過HubTeaser)和/hub頁面上渲染。請參閱參考章節了解選擇器和管理員讀取方式。
階段 0 — 範圍界定並合併網站修正
-
找出哪些是網站相關且尚未合併的內容。 工作目錄通常同時包含網站與非網站的變更。這裡只合併網站的修正(其餘部分屬於另一個關注領域)。
git status --short web/site/ git status --short -- ':!web/site/' # 非網站的變更,通常保留這些 git log --oneline origin/main..HEAD -- web/site/ # 尚未推送的網站提交 -
合併前進行本地驗證(關卡)。 針對已在執行的開發伺服器執行網站,並使用 agent-browser 檢查變更過的表面:淺色 + 深色模式、桌面 + 行動裝置、你修改的特定互動,以及控制台/網路是否乾淨。這是合併前的最終關卡;請勿提交有視覺回歸的變更。(如果開發伺服器未啟動,請在一個閒置 port 上執行
cd web/site && npm run dev,驗證完後再停止它。) -
本地建置(捕捉開發伺服器隱藏的型別/建置錯誤):
cd web/site && npm run build在建置失敗時先修正錯誤再繼續。
-
提交到 main 並推送。 依照專案慣例,直接提交到
main(除非被要求,否則不要自動建立功能分支)。將提交範圍限制在網站修正上;根據儲存庫的 footer 規則,共同撰寫提交訊息。git add web/site/ # 只加入你驗證過的網站修正 git commit -m "fix(site): <修改內容>" git push origin main
階段 1 — 建置與部署
從儲存庫根目錄(而非 web/site/)進行部署,因為 Vercel 會從其專案設定(rootDirectory=web/site)解析根目錄。如果從 web/site/ 內部執行,路徑會雙層巢狀化。請始終固定使用最新的 CLI(npx vercel@latest)。
cd /path/to/repo/root
rm -rf web/site/.next kb/app/.next # 清除過時的建置輸出;它們會導致上傳肥大
npx vercel@latest --prod --yes
不要使用 --archive=tgz(2026-06-26 在 CLI 54.x 版本上測量)。--archive=tgz 會將整個工作目錄樹打包成 tar 檔案,並繞過 .vercelignore,因此它會將 .git(幾乎包含所有內容)加上 kb/、.otbox/、web/site/.next-test/ 等一併上傳 — 這是一個約 3 GB / 1998 個檔案的上傳,耗時數分鐘,且曾經在建置機器上的「Extracting deployment files」階段掛起約 20 分鐘(我們實際遇到過的正式環境停滯問題)。相反地,在 vercel@latest 上預設的逐檔上傳路徑則:
- 遵守
.vercelignore→ 約 628 個檔案 / 約 40 MB, - 上傳時間約 2 秒,且從頭到尾達到 READY 狀態約需 60 秒,
- 不會遇到當初為了規避而加入
--archive=tgz的Error: Upload aborted錯誤(那個錯誤是 brew 41.x 版本的端點問題;vercel@latest已經修復,所以這個變通方案現在弊大於利)。
如果未來某個 CLI 版本使得逐檔上傳路徑再次出現問題,而你必須退回使用 --archive=tgz,請預期會有一個約 3 GB 的壓縮檔以及一次耗時數分鐘(有時會停滯)的解壓縮過程 — 如果部署在解壓縮階段卡住,請重試部署。
從輸出中擷取部署 URL/id;你將在驗證報告中引用它。
提示:你可以先驗證 Vercel 預覽部署(省略
--prod),在提升到正式環境前,針對預覽 URL 執行階段 2。這樣可以完全避免在正式環境的郵件清單上執行電子郵件擷取測試。
階段 2 — 在正式環境中驗證(透過 Workflow / ultracode 進行的即時測試框架)
證明即時網站可以運作。這個階段是一個即時測試框架:你(規劃者)為本次部署設定執行的範圍,Workflow 工具(確定性執行環境)執行它,而短暫的瀏覽器工作程序各自依型別化的 schema 回傳結果。中間狀態存在於測試框架的變數中,而非你的上下文中,因此完整的矩陣可以在不塞滿你視窗的情況下執行。此技能明確選擇使用 Workflow 編排(ultracode)。
此測試框架已與此技能一起打包並凍結:verify-site-deploy.workflow.js。不要內聯貼上腳本;請直接執行該檔案。
要檢查的項目
- 路由(每個都必須回傳 200 + 正確渲染、無控制台/網路錯誤):
/,/explorer,/hub,/schema,/docs,以及一些深層頁面的抽查:/schema/0.6.0,/docs/getting-started/installation,/docs/cli/commands,/docs/schema/trace-record。 - Viewport:桌面
1440x900與行動裝置390x844(iPhone 等級)。如果修正影響了主題,也要檢查淺色 + 深色模式。 - 每個頁面:HTTP 200、主要內容可見、在該 viewport 下無版面溢出/裁切、控制台乾淨、無失敗的網路請求、導航正常。
- 電子郵件擷取(其自己的代理,請參閱下方說明)。
電子郵件擷取驗證(請勿污染正式環境清單)
/api/waitlist 會寫入一個即時儲存服務,且沒有 DELETE 端點,因此請謹慎操作:
- 真正的完整來回測試(執行一次,桌面環境):提交一個帶有標籤的地址,例如
deploy-verify-<timestamp>@opentraces.ai。預期會收到 HTTP 200{ok:true}且按鈕切換為成功狀態。使用管理員讀取(GET /api/waitlist+Authorization: Bearer $WAITLIST_ADMIN_TOKEN)確認資料已持續儲存,記錄前後的計數。然後清理它,從儲存服務中移除該行(UpstashZREM),並重新讀取以確認計數已恢復。保持清單的原始狀態。 - 重複路徑:提交相同的地址兩次,預期會看到「你已在清單上」的訊息,且計數不變。
- 行動裝置 + 不寫入資料的重複 UI 檢查:在提交時填入隱藏的蜜罐陷阱(
input[name=company])。端點會回傳一個無聲的假成功訊息,且永遠不會儲存該行,因此你可以在行動裝置上確認成功 UI 而不會產生垃圾資料。(如果你看到「成功」但計數沒有變動,那是蜜罐陷阱在正常運作,並非錯誤。) - 如果端點回傳 503(「waitlist is not configured」),則表示 KV 儲存服務在該部署上未正確連接:這是 BLOCKED 狀態(環境/儲存服務問題),而非程式碼修正。請回報此問題。
執行測試框架
使用 Workflow 工具呼叫打包好的工件。根據部署情況使用 args 設定其範圍(這是即時「規劃者」步驟):
Workflow({
scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
args: {
baseUrl: "https://www.opentraces.ai", // 正式主機;或預覽 URL 以避免將電子郵件寫入正式環境
changed: ["/hub", "/"], // 本次部署修改的路由 -> 深度檢查;其餘路由僅快速檢查
pagesOnly: false // true = 跳過電子郵件寫入(僅執行唯讀驗證)
}
})
它會回傳 { base, scoped, failures, allGreen }。allGreen: true 表示階段 2 通過;否則 failures 會列出階段 3 需要修正的項目。
測試框架如何應用即時原語(請參閱 kb/docs/concept-jit-harnesses-generic.md):
- 分類與路由:如果你傳遞了
changed,那些路由會進行完整的瀏覽器檢查(控制台、溢出、螢幕截圖);其他所有路由則僅以快速的curl檢查狀態。由執行環境控制的純 JS 流程,模型中沒有接縫,因此範圍限定的部署可以保持低成本。 - 每個 viewport 一個確定性掃描工作程序(2 個工作程序,而非約 18 個):每個工作程序在一個便宜的模型(
haiku)上執行一個單一的固定 bash 批次(每個路由執行curl+ 一組有界的 agent-browser 呼叫),並回傳解析後的 JSON。沒有開放式的「驗證所有內容」提示,因此模型無法循環;每個批次只開啟一個瀏覽器 session 並執行close --all關閉它,因此 Chrome 處理程序不會堆積。(2026-06-09 驗證:完整深度 viewport 掃描約 16 秒,遺留 1 個處理程序,而原始基於每個儲存格的設計則有 54 個處理程序 / 15 分鐘以上。) - 獨立對抗性確認:任何被掃描工作程序標記為失敗的路由,都會由一個獨立的工作程序使用全新的 session(預設模型)重新檢查,嘗試重現該錯誤;只有當確認工作程序也失敗時,該失敗才會被視為存活,因此 agent-browser 的操作失誤不會偽裝成網站錯誤。
- 型別化合約:每個工作程序都會根據
PAGE_VERDICT/EMAIL_VERDICT回傳結果,因此結果可以機械性地合併。 - 電子郵件擷取有自己的工作程序,透過獨立的管理員讀取證實寫入成功,並清理測試資料列(請參閱上述無污染規則)。
若要更改矩陣、深度策略或判決 schema,請編輯 .js 檔案,它是唯一的真實來源。如果變更只涉及一個頁面且你不想使用編排,你仍然可以在主 session 中使用 agent-browser 技能依序執行該頁面的檢查。
階段 3 — 分類與迭代
讀取 workflow 的 failures:
- 空 -> 目標已達成。回報:部署 id/URL、驗證過的路由、viewports、電子郵件完整來回測試已驗證且已清理。完成 (DONE)。
- 非空 -> 對於每個失敗,在
web/site/的來源碼中找到根本原因,修正它,然後回到階段 0(本地驗證 -> 提交 -> 推送 -> 部署 -> 重新驗證)。首先針對失敗的路由執行範圍限定的重新驗證,待它們都綠燈後再進行一次完整的全面檢查。 - 在對同一個失敗進行 3 次不成功的嘗試後,或者遇到憑證/儲存服務/驗證阻礙時,請停止並以 BLOCKED 狀態回報,同時附上確切的錯誤資訊與你嘗試過的方法。
在執行記錄中記錄每次迭代,以便循環過程可供審計。
.vercelignore
位置很重要:生效的檔案是儲存庫根目錄下的 .vercelignore。 即使專案的根目錄是 web/site,整個儲存庫仍會被上傳(建置時會讀取 ../../src/opentraces/__init__.py 和 ../../skill/SKILL.md),而且逐檔上傳路徑只會遵循儲存庫根目錄下的 .vercelignore — 模式的比對是相對於儲存庫根目錄進行的。web/site/.vercelignore 會被忽略;請不要建立一個(2026-06-26 透過 npx vercel@latest --debug 驗證)。
這是一個正面排除清單(明確列舉目錄,而非使用帶有 ! 否定模式的 * 全部捕獲 — 否定模式很脆弱且會在不同 CLI 版本間失效)。沒有它的話,上傳內容會包含龐大的儲存庫資料樹。必須排除的大目錄(每個都是我們修正過的實際洩漏):
kb/(~2.4 G),.claude/(~1.5 G),tests/(~1.4 G),.venv*/(~0.8 G).otbox/(~613 M 的快照 tar 檔)web/site/.next-test/(~98 M / 1000 多個檔案 — 注意**/.next/不會匹配到-test後綴,因此.next-test/需要自己的規則)web/viewer/,web/coming-soon/,web/metrics-worker/
警告:
.vercelignore只會過濾逐檔上傳路徑。--archive=tgz標誌會繞過它(參閱階段 1 — 這是另一個不使用它的原因)。
若要在編輯 .vercelignore 後檢查上傳內容是否合理,請從儲存庫根目錄執行 npx vercel@latest --debug,並讀取 Found N files … M required to upload 這行,然後按 Ctrl-C — 無需完整部署。一個健康的網站部署約有 628 個檔案,而非約 2000 個。
不得被忽略的檔案(在建置時會被讀取):
| 檔案 | 被誰讀取 | 用途 |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | 為 version.json 進行版本偵測 |
skill/SKILL.md | lib/docs.ts (getSkillContent()) | 文件頁面上的機器檢視內容 |
如果你新增了一個網站會在建置時透過相對路徑(例如 ../../foo)讀取的檔案,請確保它沒有被 .vercelignore 排除。
參考資料
路由(階段 2 矩陣):/, /explorer, /hub, /schema,
/schema/[version], /docs, /docs/[[...slug]](來自 lib/doc-nav.ts 的約 36 個文件 slug)。API:/api/waitlist(POST 新增,GET 管理員讀取)、/api/stars。
電子郵件表單選擇器(EarlyAccessForm.tsx):電子郵件輸入框 input[type=email] / aria-label="email address" / .ea-input;提交按鈕 button.ea-btn(「get early access」 -> 載入中 -> 成功);隱藏的蜜罐陷阱 input[name=company](填入它 -> 無聲的假成功,永遠不會儲存)。
Waitlist 管理員讀取:GET /api/waitlist 附帶 Authorization: Bearer $WAITLIST_ADMIN_TOKEN。回傳一個包含 count、emails(物件陣列,每個物件有 id 和 email)的 JSON 物件。使用 count 來驗證寫入/刪除,使用 emails 來尋找並清理測試資料列(Upstash ZREM list emails {id})。
快取清除:Vercel 正式部署會使 CDN 邊緣快取失效。但是,如果一個靜態路徑(例如 /)在你定址一個動態路由(例如 /api/waitlist)時沒有更新,請考慮在 Vercel 專案儀表板中「清除 CDN 快取」,或者重新部署。不需要手動瀏覽器硬重新整理(那是代表使用者端的問題)。