受保護的 Vercel 部署 是做什麼的？
使用呼叫者現有的 Vercel 身分和短期有效的 OIDC 令牌。請勿停用部署保護、將部署設為公開，或先要求靜態繞過密鑰。
相同專案預覽
目標專案的本地開發令牌可以透過預設的 Trusted Sources 自我存取規則來存取該專案受保護的預覽部署。通常不需要設定 Trusted Sources。
確認本地身分和 Vercel CLI 版本：
vc whoami
vc --version
在執行 vc project token 之前，需要 Vercel CLI 53.3.0 或更新版本。版本 50.25.0 到 53.2.x 會將令牌寫入 stderr，因此命令替換會無法捕捉到任何內容，且憑證可能會出現在日誌中。如果已安裝的版本較舊，請停止並要求使用者升級。請勿嘗試從 stderr 捕捉或復原令牌。
明確設定目標專案和範圍。如果無法安全推斷，請詢問使用者。在目錄中，如果現有的 .vercel/project.json 連結已針對目標進行驗證，則在沒有專案名稱的情況下執行 vc project token 也是有效的。請勿僅為了取得 OIDC 令牌而執行 vc link：目前的 Vercel CLI 版本在連結時也會將開發變數拉入 .env.local。
建立一個具名瀏覽器工作階段，使用 Vercel CLI 產生開發 OIDC 令牌，然後注入令牌，不要列印或持久化儲存：
export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)"
export VERCEL_PREVIEW_URL="https://my-app.vercel.app"
export VERCEL_PROJECT="my-app"
export VERCEL_SCOPE="my-team"
(
TOKEN="$(vc project token "$VERCEL_PROJECT" --scope "$VERCEL_SCOPE")"
test -n "$TOKEN"
agent-browser open "$VERCEL_PREVIEW_URL" --headers \
"{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}"
)
agent-browser snapshot -i
在同一個工作階段中繼續正常的工作流程。此標頭作用於目標來源，並適用於文件、腳本、樣式、字型和頁面內的請求。如果瀏覽器工作階段關閉或重新啟動，請重複執行經過驗證的 open 命令。
切勿列印令牌、將其貼上到原始碼中，或將其儲存在環境檔案中。
其他環境和呼叫者
在以下情況需要設定 Trusted Sources：
- 本地開發令牌必須存取受保護的生產部署；
- 呼叫者屬於另一個 Vercel 專案或團隊；
- 目標專案的自我存取規則已自訂；或
- Vercel 回傳
TRUSTED_SOURCES_ENVIRONMENT_MISMATCH。
沒有支援的 Vercel CLI 或公開 REST API 可用於編輯 Trusted Sources 規則。必須由授權人員開啟目標專案的 Settings → Deployment Protection → Trusted Sources，並僅新增所需的呼叫者和環境對應。本地令牌具有 development 環境，因此受保護的生產存取需要 development 到 production 的對應。
請停止並將確切的規則移交給人員。請勿使用瀏覽器自動化來變更存取控制，也請勿擴大不相關的環境對應。在人員確認規則已儲存後，重試經過驗證的 open 命令。
人為介入邊界
當 Vercel CLI 已通過驗證且目標專案和範圍已知時，相同專案的開發到預覽路徑應該在無人為介入的情況下執行。僅在以下情況需要人為介入：
- Vercel CLI 沒有已驗證的身分且沒有現有的
VERCEL_TOKEN；互動式vc login需要使用者； - 已安裝的 Vercel CLI 版本舊於
53.3.0，必須在產生令牌前升級； - 無法安全推斷正確的目標專案或範圍以進行令牌產生；
- 必須新增或變更 Trusted Sources 規則；儀表板是唯一受支援的管理介面，且這會變更存取控制；
- 呼叫專案的 OIDC Federation 的安全後端存取已停用，必須在 Settings → Security 中重新啟用；或
- 必須啟用或輪換靜態密鑰後備方案，且代理需要明確授權才能進行此存取控制變更。獲得批准後，代理可以使用
vc project protection而不是要求儀表板互動。
代理可以診斷每種情況並說明所需確切動作，然後在使用者確認完成後繼續。
使用正確的標頭
將 Vercel 發出的令牌作為：
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
請勿替代為 x-vercel-oidc-token。該標頭將工作負載身分帶入 Vercel Function；它不會在通過部署保護時驗證傳入請求。
診斷失敗
- 重新導向到
vercel.com/login：部署保護未接受請求。 TRUSTED_SOURCES_ENVIRONMENT_MISMATCH：令牌有效，但其呼叫者環境無法到達目標環境。- 通過保護後應用程式回傳
401或403：請單獨除錯應用程式自身的驗證機制。 - 在刻意缺少的路由上應用程式回傳
404：請求已通過部署保護並到達應用程式。
靜態密鑰後備方案
僅在 OIDC 不可行或工具無法傳送 Trusted Sources 標頭時，才使用 Protection Bypass for Automation。啟用或輪換它會變更存取控制，因此請先取得明確授權。建立一個專用密鑰，以便可以獨立輪換，將其儲存在環境變數中，並作為標頭傳遞：
vc project protection enable <project> --protection-bypass \
--protection-bypass-secret "$VERCEL_AUTOMATION_BYPASS_SECRET"
agent-browser open "$VERCEL_PREVIEW_URL" --headers \
"{\"x-vercel-protection-bypass\":\"$VERCEL_AUTOMATION_BYPASS_SECRET\",\"x-vercel-set-bypass-cookie\":\"true\"}"
Cookie 指令會建立一個可重複使用的 _vercel_jwt cookie。請將包含該 cookie 的已儲存瀏覽器狀態視為憑證。
避免死路
- 沒有
vercel shareCLI 命令。可分享連結是為人員設計的，不是自動化路徑。 vercel curl對 HTTP 請求很有用，但它無法渲染頁面並與之互動。- 部署保護例外會使網域變成公開。請勿僅為了解除代理封鎖而使用它們。
- 請勿將 OIDC 令牌、繞過密鑰、經過驗證的 URL 或已儲存狀態暴露在日誌、螢幕截圖、原始碼檔案或用戶可見的輸出中。