行銷網站開發 (火山引擎)
用於建置並將雙語靜態公司行銷網站部署至火山引擎的端到端技能。分為兩個階段:
- 建置 — Astro 6 + React 19 島架構(僅行動選單) + Tailwind 4。全面使用內嵌 SVG。單一內容檔案(
src/content/site.ts)為唯一事實來源。 - 部署 — TOS 儲存桶 + CDN + 免費 DV 憑證 + HTTPS 強化,全部透過
veCLI 和火山引擎 OpenAPI(透過volc-api.mjs使用 SigV4 簽署,用於ve未提供的操作)在冪等的 Node 腳本中編寫。
成功的定義: 使用者執行約 6 個指令端到端,即可獲得 https://<他們的網域>/ 提供一個具備 HTTPS、HTTP 強制重導至 HTTPS、HSTS、HTTP/2、邊緣快取和自動快取失效的生產級雙語網站。每個基礎設施步驟都作為一個冪等腳本保存在版本控制中。
這個技能合適嗎?
這是一個刻意設計、帶有強烈意見的工作流程,針對一個特定情境進行了最佳化。在深入之前,請確認該情境確實符合使用者的情況。如果不符合,請提出更好的替代方案,而不是強迫使用者走一條更複雜的路。
在以下情況使用此技能:
- 網站是為中國公司或目標用戶在中國大陸的產品而建置 — 從中國大陸連線至非中國 CDN 的延遲相當高(200-400 毫秒,尖峰時段更糟),訪客會明顯感覺到並可能因此跳出。
- 需要或已擁有 ICP 備案 — 在中國合法分發內容需要與託管在中國雲端上的網域進行備案綁定。火山引擎提供備案協助,並可為您在此部署的網域提供服務。
- 使用者已處於火山引擎生態系統中(使用其他火山引擎服務、現有 TOS 儲存桶等),整合具有價值。
- 需要中英文雙語模式 — 內容層(
site.ts)正是為此設計的。
在以下情況使用更簡單的替代方案:
| 情境 | 建議的替代方案 | 原因 |
|---|---|---|
| 個人網站 / 作品集 / 副業專案,無中國觀眾需求 | GitHub Pages | 免費、自動 HTTPS、git push 即可部署,無需管理基礎設施。零個火山引擎的潛在問題。 |
| 僅面向國際觀眾(美國/歐盟/東南亞),無中國市場計畫 | Vercel(或 Cloudflare Pages / Netlify) | 免費方案、從 Git 即時部署、每個 PR 有預覽 URL、自動 HTTPS、全球邊緣網路。完全跳過 ve CLI + ICP 工作流程。 |
| 網站需要無伺服器函數(表單、驗證、動態內容) | Vercel 或 Cloudflare Pages 搭配其邊緣函數 | 此技能僅提供靜態內容 — 火山引擎有無伺服器產品,但此工作流程未涵蓋。 |
| 你需要每個分支 / PR 的預覽 URL 進行審查 | Vercel | Vercel 的預覽 URL 體驗是同類最佳。此技能每次推送僅產生一個生產部署;沒有分支預覽。 |
如果使用者的情況符合「建議的替代方案」欄位,請在建置任何東西之前明確告知他們。當使用者不需要火山引擎提供的功能時,花 2 分鐘用 Vercel 部署會比花 30 分鐘引導使用火山引擎更好。不要因為他們呼叫了這個技能就讓他們投入錯誤的技術棧。
如有疑問,請詢問:「中國大陸的用戶會是您觀眾群中的重要部分嗎?您是否擁有(或計畫申請)該網域的 ICP 備案?」如果兩個答案都是「否」,請直接指向 Vercel / GitHub Pages 並停止。
步驟 1:捕捉意圖(永遠先問)
在從使用者那裡獲得以下六項輸入之前,請不要編寫任何程式碼。如果提示中缺少這些資訊,請透過 AskUserQuestion 提問。大多數團隊會擁有所有資訊,可能除了公安備案號 — 該項可以先用佔位符代替。
| # | 輸入 | 用途 | 備註 |
|---|---|---|---|
| 1 | 公司名稱(中文 + 英文) | site.ts 中的 COMPANY.nameZh / COMPANY.nameEn;頁尾;SEO | |
| 2 | 網域(例如 example.com) | 任何地方 — 儲存桶綁定、CDN、DNS、憑證 SAN | 必須已經 ICP 備案,且最好託管在火山引擎 DNS 上。如果託管在其他地方,使用者需要手動新增 CNAME 和 TXT 記錄。 |
| 3 | 品牌資產目錄(SVG 標誌檔案的路徑) | 內嵌 BrandMark.astro 提取(短版標誌 SVG 的最後 3 個路徑) | 通常是類似 assets/logo/svg/Tenshow_short1.svg 的短版 / 僅圖示的變體。 |
| 4 | 產品列表 | site.ts 中的 PRODUCTS[] | 每個產品需要雙語名稱 + 描述、URL、強調色十六進位碼、圖示列舉值。 |
| 5 | ICP 備案號 | 頁尾 | 工信部核發的備案號。 |
| 6 | 工作目錄 | 專案根目錄 | 應該是全新(空的)目錄,否則你必須協調現有檔案。 |
可選:
- 公安備案號 — 在建置時通常用佔位符代替。請在 README 中明確標記,以便使用者在啟動前替換它。
- 品牌強調色 — 從標誌 SVG 的十六進位值中提取。如果無法決定,預設使用主色中非中性的顏色。
步驟 2:建置靜態網站
完整細節請參閱 references/phase-1-static-site.md。摘要如下:
- 建置腳手架 — 將
assets/templates/package.json和assets/templates/astro.config.mjs複製到專案根目錄。更新package.json中的name和astro.config.mjs中的site。 - 安裝套件 —
pnpm install。 - 安裝 Astro 代理技能 — 僅在
pnpm install成功後執行:
如果技能安裝失敗,請繼續進行網站建置,並記錄失敗訊息,讓使用者稍後重試;不要因此阻塞工作流程。npx skills add https://github.com/astrolicious/agent-skills --skill astro - 建立源代碼目錄樹 — 使其符合 phase-1-static-site.md 中的佈局(
src/content/site.ts、src/components/、src/layouts/BaseLayout.astro、src/pages/index.astro、src/pages/en/index.astro、src/styles/global.css)。 - 提取品牌標記 — 從使用者的 SVG 中提取,使用
assets/templates/BrandMark.astro作為起點。短版標誌 SVG 的最後 3 個<path>元素即為標記;逐字複製它們並從品牌色板中選取填充色。 - 建置章節 — Hero(使用 phase-1-static-site.md 中的精確配方 — 網格背景 + 徑向光暈 + 漸層標題 + 狀態標籤 + 2 個 CTA 按鈕)、關於我們、產品、焦點、最新消息、聯絡我們、頁尾。頁首固定,行動選單 = 唯一的 React 島。
- 在本地驗證 —
pnpm dev進行開發,pnpm build && pnpm preview在接觸基礎設施前檢查靜態輸出是否正常。
技術棧鎖定(請勿偏離)
Astro 6、React 19(僅行動選單)、透過 @tailwindcss/vite 使用的 Tailwind 4、pnpm 10、Node 22+、TypeScript 嚴格模式、零外部圖片、零 UI 函式庫、零字型服務、系統字型堆疊。理由和完整細節請參閱 phase-1-static-site.md。
步驟 3:設定部署基礎設施
完整細節請參閱 references/phase-2-volcengine-deploy.md。請先閱讀 references/landmines.md — 在此階段,你一半的時間都在避免踩雷,而不是執行指令。
- 複製腳本 — 將整個
assets/scripts/目錄和assets/cdn-payloads/分別複製到使用者的scripts/和scripts/cdn-payloads/目錄。將assets/templates/deploy.config.mjs複製到專案根目錄,並填入bucket、region、endpoint、cdnDomains。 - 取代 Payload 中的佔位符 — 取代
scripts/cdn-payloads/apex.json和www.json中的{{DOMAIN}}、{{BUCKET}}、{{REGION}}。OriginHost必須是網域本身,不能為空 — 模板預設是正確的;如果你編輯它們,請保留OriginHost。請參閱 landmines.md #3。 - 建立
.env檔案於專案根目錄(已加入 gitignore):
火山引擎 AK/SK 需要VOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess、CDNFullAccess、DNSFullAccess、CertificateFullAccess(或最小權限等價設定)。 - 確認
ve已安裝:ve version— 需要 1.0.x 或更高版本。如果缺少,請依照火山引擎官方文件安裝。
步驟 4:執行首次部署
pnpm install # 如果尚未完成
npx skills add https://github.com/astrolicious/agent-skills --skill astro # 如果尚未完成
pnpm build # 驗證本地建置是否正常
pnpm run setup:bucket # 冪等:建立儲存桶 + 網站路由 + 自訂網域綁定
pnpm run deploy:upload # 同步 dist/ → 儲存桶
# 此時:https://<bucket>.tos-<region>.volces.com/index.html 應該回傳 200
pnpm run setup:cdn # 驗證所有權 → 新增 CDN → CNAME → 憑證 → HTTPS 強化
# 等待 1-3 分鐘讓 DNS 傳播
pnpm run cdn:refresh # 清除邊緣快取,確保首次訪問不會回傳儲存桶列表 JSON
在這次初始執行之後,日常迭代只需一個指令:
pnpm run deploy && pnpm run cdn:refresh
務必使用 pnpm run,而不是單純的 pnpm
pnpm deploy 是 pnpm 的內建工作區指令 — 它會在非工作區的環境中報錯 ERR_PNPM_CANNOT_DEPLOY。請使用 pnpm run deploy 和 pnpm run cdn:refresh。在專案的 README 中記錄此點。請參閱 landmines.md #6。
步驟 5:驗證
執行 references/verification.md 中的 curl + openssl 檢查清單。預期結果:關鍵路由上 5 次 HTTP 200,HTTP → HTTPS 上 1 次 301 重導,有效憑證其 SAN 涵蓋頂級網域和 www 子網域,確認 HTTP/2 + HSTS,Cache-Control 標頭符合 deploy.config.mjs 規則。
如果任何檢查失敗,verification.md 會將每種失敗模式對應到根本原因和修復方法。
執行前必須知道的關鍵地雷
完整列舉請參閱 landmines.md。如果你跳過閱讀,你可能會遇到以下問題:
HTTPS_PROXY污染 — TOS SDK + 本地 HTTP Proxy =Protocol "http:" not supported。assets/scripts/中的每個腳本已在頂部刪除了 Proxy 環境變數 — 如果你複製或改編它們,請保留該前綴程式碼。- TOS SDK 怪癖 —
headBucket(string)而非headBucket({bucket});當continuationToken: undefined存在於輸入中時,listObjectsType2簽章會中斷;putObject即使在公開讀取的儲存桶上也預設為私有 — 務必設定acl: 'public-read'。 - TOS 沒有單獨的網站端點主機名稱 — 同一個
<bucket>.tos-<region>.volces.com會根據Host標頭回傳儲存桶列表 JSON 或index.html。你必須 (a) 為每個頂級/www 網域呼叫putBucketCustomDomain,並且 (b) 在 CDNAddCdnDomainpayload 中將OriginHost設定為使用者的網域(不能為空)。 - 驗證時 CDN ≠ DCDN — CDN(內容分發網路)想要 TXT 主機記錄
volccdnauth,並使用cdn:CheckCdnDomain(不在veCLI 中 — 使用volc-api.mjs)。DCDN(全站加速)使用_dnsauth和ve dcdn VerifyDomainOwnership。混淆它們 = 無止盡的驗證循環。 - TXT 變更需要約 10 分鐘傳播到火山引擎的驗證器。第一次寫入時就讓值正確;不要反覆修改。
pnpm deploy是內建指令。 請使用pnpm run deploy。- 免費 DV 憑證的申請僅限控制台。 使用永久 AK/SK 透過 API 簽發會失敗 (
OperationDenied.RequestFreeInstance)。但列出已簽發的憑證是可行的 — 免費 DV 憑證通常會在網域註冊時自動簽發。務必先呼叫CertificateGetInstanceList;在Result.Instances[]中尋找(不是InstanceList,也不是Data),尋找一個其San涵蓋頂級網域和 www 子網域的憑證。
行為規則
- 先計畫;在執行破壞性操作前確認。 在執行
createBucket、AddCdnDomain、DeleteRecord(針對現有 TXT 記錄)或BatchDeployCert之前,先總結即將發生的操作並向使用者確認。 - 在寫入之前先讀取現有狀態。 務必先執行
ListRecords/ListCdnDomains/CertificateGetInstanceList— 免費憑證通常已預先簽發、CDN 網域可能已存在、DNS 記錄可能已指向正確位置。冪等性是重點。 - 當
ve缺少某個操作時,使用volc-api.mjs,而不是告訴使用者升級ve或使用控制台。唯一真正的僅限控制台路徑是免費 DV 憑證簽發(landmines.md #4)。 - 不要頻繁修改 DNS 記錄。 每次 TXT 修改都會增加約 10 分鐘的快取時間。第一次就讓主機/值正確 — CDN 用
volccdnauth,DCDN 用_dnsauth,它們不能互換。 - 將每個設定決策都放在
deploy.config.mjs中, 永遠不要硬編碼在腳本裡。儲存桶、區域、端點、CDN 網域、快取規則 — 全部放在設定檔中,這樣使用者可以編輯一個檔案來改變所有設定。 /usr/bin/curl比單純的curl更可靠,在長時間指令後於同一個 shell 中執行檢查時 — bash 的 PATH 查找偶爾會出問題。CI 腳本中的測試也是如此。
打包的資產和參考資料
assets/scripts/(逐字複製到使用者的 scripts/ 目錄)
lib/volc-api.mjs— SigV4 簽署器,無依賴。用於veCLI 缺少的任何操作。setup-bucket.mjs— 冪等:建立儲存桶 + 網站設定 + 自訂網域綁定。deploy.mjs— TOS 同步上傳器,支援按前綴設定Cache-Control,以及孤兒檔案刪除。cdn-setup.mjs— CDN 編排:所有權驗證 → AddCdnDomain → CNAME → 憑證 → HTTPS 強化。cdn-refresh.mjs— 透過cdn:SubmitRefreshTask進行快取失效(由volc-api.mjs簽署,可在沒有ve的 CI 環境中運作)。
assets/cdn-payloads/(複製到 scripts/cdn-payloads/)
…[為翻譯而截斷]