Vercel 受保护部署 是做什么的？
使用调用者现有的 Vercel 身份和短期 OIDC 令牌。不要禁用部署保护、将部署设为公开或首先请求静态绕过密钥。
同一项目预览
用于目标项目的本地开发令牌可以通过默认的可信来源自访问规则访问该项目的受保护预览部署。通常不需要配置可信来源。
确认本地身份和 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 命令。
永远不要打印令牌、粘贴到源代码中或保存在环境文件中。
其他环境和调用者
当以下情况时需要配置可信来源：
- 本地开发令牌必须访问受保护的生产部署；
- 调用者属于另一个 Vercel 项目或团队；
- 目标项目的自访问规则已被自定义；或
- Vercel 返回
TRUSTED_SOURCES_ENVIRONMENT_MISMATCH。
没有受支持的 Vercel CLI 或公共 REST API 用于编辑可信来源规则。授权人类必须打开目标项目的 设置 → 部署保护 → 可信来源 并仅添加所需的调用者和环境映射。本地令牌具有 development 环境，因此受保护的生产访问需要将 development 映射到 production。
停止并将确切的规则移交给人类。不要使用浏览器自动化更改访问控制，也不要扩大无关的环境映射。在人类确认规则已保存后，重试经过身份验证的 open 命令。
人工干预边界
当 Vercel CLI 已经过身份验证且目标项目和范围已知时，同一项目的开发到预览路径应该无需人工干预即可运行。仅在以下情况下需要人工：
- Vercel CLI 没有经过身份验证的身份且没有现有的
VERCEL_TOKEN；交互式vc login需要用户操作； - 安装的 Vercel CLI 版本低于
53.3.0，必须在生成令牌前升级； - 无法安全推断正确的目标项目或范围用于生成令牌；
- 必须添加或更改可信来源规则；仪表盘是唯一受支持的管理界面，且此操作会更改访问控制；
- 调用项目上的通过 OIDC 联合的安全后端访问被禁用，必须在 设置 → 安全 中重新启用；或
- 必须启用或轮换静态密钥回退，并且代理需要明确授权以进行该访问控制更改。获得批准后，代理可以使用
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 不可用或工具无法发送可信来源标头时，才使用用于自动化的保护绕过。启用或轮换它会更改访问控制，因此请先获得明确授权。创建一个专用密钥，以便可以独立轮换它，将其保存在环境变量中，并作为标头传递：
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 或已保存的状态。