mcpField
A
access-protected-vercel-deployment

access-protected-vercel-deployment

github.com/vercel云与 DevOps3182.6k 次安装2 天前更新
代码仓库

关于 access-protected-vercel-deployment

用于访问受 Deployment Protection 保护的 Vercel 部署的 Skill，使用调用方现有身份验证。内容涵盖 HTTP 请求、浏览器自动化中的短期 OIDC 令牌，以及在不关闭保护的情况下排查访问错误。

主要功能

  1. 01使用 vercel curl 访问部署
  2. 02为浏览器请求添加 OIDC 令牌头
  3. 03检查身份与项目关联
  4. 04排查 Trusted Sources 错误
  5. 05保护令牌和部署设置

适用场景

  1. 01检查受保护部署的健康端点
  2. 02调用受保护部署上的 API
  3. 03自动化访问预览环境的浏览器
  4. 04排查受保护生产环境的访问问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel/vercel-plugin --skill access-protected-vercel-deployment

安装后在 Claude Code 中输入/access-protected-vercel-deployment确认已加载。

附带文件.vercel.approvers

详细介绍

访问受保护的 Vercel 部署

使用调用者现有的 Vercel 身份验证。不要禁用 Deployment Protection，也不要首先要求提供长期有效的绕过密钥。

选择访问方式

HTTP 请求：使用 vercel curl

对于响应正文、标头、健康检查和 API 调用，请用 vercel curl（vc curl）替代原始 curl。它接受原生的 curl 选项，并使用 Vercel 身份验证访问受保护的预览版和生产部署。

vc curl https://my-app.vercel.app/api/health
vc curl https://app.example.com/api/health
vc curl my-app.vercel.app/api/users -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'
vc curl /api/health

仅指定路径时，目标为已关联项目的生产部署。若需访问特定部署，请传入完整 URL。

如果身份验证失败，请先检查本地身份和项目，再更改保护设置：

vc whoami

检查 .vercel/project.json，确认已关联的项目和团队。仅当目录未关联项目或关联了错误的项目时，才运行 vc link。仅当 CLI 报告没有可用的已验证用户时，才运行 vc login。

浏览器自动化：将开发 OIDC 令牌作为标头附加

浏览器请求必须在请求标头中包含短期有效的本地令牌：

x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>

使用支持按源设置请求标头的浏览器工具。使用 agent-browser 时，注入开发环境变量，但不要打印或持久化令牌：

vc env run -- sh -c \
  'test -n "$VERCEL_OIDC_TOKEN" && agent-browser open "$1" --headers "{\"x-vercel-trusted-oidc-idp-token\":\"$VERCEL_OIDC_TOKEN\"}"' \
  sh https://my-app.vercel.app

然后在同一会话中继续正常的浏览器工作流。对于 Playwright 或其他浏览器驱动程序，请在首次导航前，将相同的标头设置为浏览器上下文的额外 HTTP 标头。

如果本地 CLI 版本无法通过 vc env run 提供令牌，请刷新本地开发凭据：

vc env pull .env.local --yes

通过项目现有的 dotenv 机制加载该文件。切勿打印令牌、将其值粘贴到源代码中，或提交 .env.local。

对于 Trusted Sources，请使用 x-vercel-trusted-oidc-idp-token。不要替换为 x-vercel-oidc-token；该标头会将 OIDC 令牌传递给 Vercel Function，作用不同。

Trusted Sources 规则

已关联 Vercel 项目的本地开发令牌默认可以访问同一项目的预览部署，但不会自动访问受保护的生产部署。要访问受保护的生产部署，项目自身的 Trusted Sources 条目必须允许 development → production。

对于通常的同项目预览场景，不要要求用户配置 Trusted Sources。

以下情况需要配置：

  • 目标是受保护的生产部署，且调用者使用本地开发令牌；
  • 调用者属于另一个 Vercel 项目或团队；
  • 目标项目的自访问规则已自定义；或
  • 响应为 TRUSTED_SOURCES_ENVIRONMENT_MISMATCH。

在目标项目中，打开 Settings → Deployment Protection → Trusted Sources。添加或编辑调用者，并允许所需的 from → to 环境组合。本地令牌的环境为 development，因此要访问受保护的生产部署，必须允许 development → production。

请将此操作视为访问控制变更：说明所需的确切规则，并在更改前取得授权。不要扩大无关的环境组合范围。

诊断响应

  • 如果出现 Vercel 登录、SSO 或 Deployment Protection 页面，说明请求未使用受认可的身份验证方式。
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH 表示令牌有效，但不允许其调用者环境访问目标环境。
  • 绕过 Vercel 保护后，如果出现应用生成的 401 或 403，则属于应用自身的身份验证问题，必须单独调试。
  • 标记为 "target": "production" 的部署仍可能受保护。不要假定生产部署是公开的。

避免

  • 不要为了让自动化通过而禁用部署保护。
  • 收到保护页面后，不要反复发送未经身份验证的原始 curl 请求。
  • 如果 vc curl 或限定来源的 OIDC 标头可以验证请求身份，就不要启动交互式 SSO 浏览器登录。
  • 不要在日志、屏幕截图、已提交的文件或面向用户的输出中泄露 VERCEL_OIDC_TOKEN。

相关技能

  • Vercel CLI 常规用法：⤳ skill: vercel-cli
  • 端到端应用验证：⤳ skill: verification

评论

支持 Markdown