publish 是一個很薄的客戶端。它不編譯、不打包,也不上傳任何東西。它向平台送出一個帶身分驗證的請求,然後印出平台回覆的那個 URL。
何時使用 publish
- 給審閱者一個建置連結,而不是一個 zip 檔。
- 在
build產出產物之後,把分享連結接進 CI。 - 把分享連結釘在某一個特定建置上,而不是專案的最新建置。
publish 解析的是一個已經存在於 extension.dev 上的專案,所以它需要平台已經記錄過的建置。如果你想把此刻還躺在自己 dist/ 裡的建置寄給別人,請改為上傳那個建置:Share an unpublished build for review。
publish 會與 extension.dev 平台溝通,而它是獨立於 Extension.js
的另一個產品。那些在你機器上執行的 Extension.js
指令(create、dev、build、preview、start)從來不需要帳號,publish 需要。用法
權杖需求
沒有存取權杖時,publish 拒絕執行。它依下列順序在三個地方尋找:
- 指令列上的
--token <token>。 - 環境變數
EXTENSION_DEV_TOKEN(CI 中建議用這個)。 npx @extension.dev/mcp login寫下的已儲存裝置登入。
1 結束,並向 stderr 印出:
範圍檢查
一次已儲存的裝置登入只對應一個專案。從一個無關的資料夾發布,會為那個專案產生一個分享連結,而任何顯眼的地方都不會寫明它究竟屬於誰。publish 把這種不一致當成拒絕,而不是警告:
- 當資料夾的專案名稱與已儲存登入的專案對不上時,指令拒絕執行,並把兩者都列出來。
- 傳
--project <slug>,就可以在任何位置刻意發布該登入對應的專案。 - 傳入的
--projectslug 與已儲存登入不相符時,同樣會被拒絕。 - 使用
--token或EXTENSION_DEV_TOKEN提供的權杖時,會完全略過與已儲存登入的比對。
package.json、manifest.json、src/manifest.json,最後才是資料夾名稱。
參數與 flag
它會印出什麼
pretty 輸出只有一行,就是分享 URL,因此可以乾淨地接進管線:--output json 會印出一個信封。平台回應放在 value 裡,而它帶的不只是那個 URL:
value.shareUrl 與 value.visibility,沒有需要攜帶的權杖。
加上 --build-sha 時,URL 指向的是那個建置,而不是專案總覽頁:https://<workspace>.extension.dev/<project>/builds/<sha>。
公開專案與私人專案
一個專案不是公開就是私人。publish 只讀取這個設定,從不更動它。你拿到哪一種連結由平台決定:
兩種回覆指向的是同一個頁面。可見性決定的是要不要附上權杖,而不是你拿到哪個位址。
釘在某一個建置上
--build-sha 會連到某一個建置,而不是專案的最新建置。平台會拿這個 sha 去比對專案的建置索引,當沒有任何已完成的建置相符時,回覆 404 與 UNKNOWN_BUILD 代碼,所以打錯字會明確失敗,而不是產出一個指向錯誤產物的連結。
範例
在 CI 中發布
給某一位審閱者的短期連結
行為說明
publish從不編譯。想讓連結指向新鮮的輸出時,請先執行build。- 每一條失敗路徑都以結束碼
1結束:權杖缺失、平台連不上,或任何非 2xx 回應——後者會印成publish failed (<status>): <message>。 --api接受結尾有沒有斜線的基底 URL 都可以。指令會自己補上/api/cli/publish。--ttl會被平台夾在 1 到 168 小時的範圍內。- 這個指令回傳的
?share=權杖,不是那個可撤銷的 30 天預覽連結。那種連結來自另一個動作,它會上傳建置;而publish什麼都不上傳。參見 平台的 publish 頁面。
後續步驟
- 用
build產出要分享的產物。 - 先用
preview在本地驗證這些產物。 - 不用 zip、也不用安裝,把一個未發布的建置透過連結交給別人,參見 Share an unpublished build for review。
- 在 Builds 中了解建置是怎麼被記錄的。