Back to Details

access-protected-vercel-deployment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Access Protected Vercel Deployments

访问受保护的Vercel部署

Use the caller's existing Vercel authentication. Do not disable Deployment Protection or ask for a long-lived bypass secret as the first solution.
使用调用者已有的Vercel身份验证信息。不要将禁用Deployment Protection或请求长期绕过密钥作为首选解决方案。

Choose the access path

选择访问路径

HTTP requests: use 
vercel curl

HTTP请求：使用
vercel curl

For response bodies, headers, health checks, and API calls, replace raw 
curl
with 
vercel curl
(
vc curl
). It accepts native curl options and uses Vercel authentication to access protected preview and production deployments.
bash
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
The path-only form targets the linked project's production deployment. Pass a full URL when the exact deployment matters.
If authentication fails, check the local identity and project before changing protection settings:
bash
vc whoami
Inspect 
.vercel/project.json
to confirm the linked project and team. Run 
vc link
only when the directory is not linked or is linked to the wrong project. Run 
vc login
only when the CLI reports that no authenticated user is available.
对于响应体、请求头、健康检查和API调用，将原生
curl
替换为
vercel curl
（简称
vc curl
）。它支持原生curl选项，并通过Vercel身份验证访问受保护的预览和生产部署。
bash
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。
如果身份验证失败，请先检查本地身份信息和关联项目，再修改保护设置：
bash
vc whoami
查看
.vercel/project.json
以确认关联的项目和团队。仅当目录未关联项目或关联了错误项目时，才运行
vc link
。仅当CLI提示无已认证用户时，才运行
vc login
。

Browser automation: attach the development OIDC token as a header

浏览器自动化：添加开发环境OIDC令牌作为请求头

Browser requests must include the short-lived local token as a request header:
text
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
Use a browser tool that supports origin-scoped request headers. With 
agent-browser
, inject development variables without printing or persisting the token:
bash
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
Then continue the normal browser workflow in the same session. For Playwright or another browser driver, set the same header in the browser context's extra HTTP headers before the first navigation.
If the local CLI version does not provide the token through 
vc env run
, refresh local development credentials with:
bash
vc env pull .env.local --yes
Load the file through the project's existing dotenv mechanism. Never print the token, paste its value into source code, or commit 
.env.local
.
Use 
x-vercel-trusted-oidc-idp-token
for Trusted Sources. Do not substitute 
x-vercel-oidc-token
; that header carries an OIDC token into a Vercel Function and serves a different purpose.
浏览器请求必须将短期本地令牌作为请求头传入：
text
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
使用支持源范围请求头的浏览器工具。通过
agent-browser
，无需打印或持久化令牌即可注入开发环境变量：
bash
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
提供令牌，请通过以下命令刷新本地开发凭据：
bash
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 rules

可信来源规则

A local development token for a linked Vercel project can access that same project's Preview deployments by default. It does not automatically access protected Production deployments. For protected Production, the project's own Trusted Sources entry must allow 
development
→ 
production
.
Do not ask the user to configure Trusted Sources for the normal same-project Preview case.
Configuration is needed when:
  • the target is a protected Production deployment and the caller uses a local development token;
  • the caller belongs to another Vercel project or team;
  • the target project's self-access rules were customized; or
  • the response is 
    TRUSTED_SOURCES_ENVIRONMENT_MISMATCH
    .
In the target project, open Settings → Deployment Protection → Trusted Sources. Add or edit the caller and allow the required 
from
→ 
to
environment pair. A local token has the 
development
environment, so access to protected Production requires 
development
→ 
production
.
Treat this as an access-control change: explain the exact rule required and obtain authorization before changing it. Do not broaden unrelated environment pairs.
已关联Vercel项目的本地开发令牌默认可以访问同一项目的预览部署，但不会自动访问受保护的生产部署。对于受保护的生产环境，项目自身的可信来源条目必须允许
development
→ 
production
的访问。
不要要求用户为常规的同项目预览场景配置可信来源。
以下情况需要进行配置：
  • 目标是受保护的生产部署，且调用者使用本地开发令牌；
  • 调用者属于另一个Vercel项目或团队；
  • 目标项目的自访问规则已被自定义；
  • 响应提示为
    TRUSTED_SOURCES_ENVIRONMENT_MISMATCH
    。
在目标项目中，打开设置 → 部署保护 → 可信来源。添加或编辑调用者信息，并允许所需的
from
→ 
to
环境配对。本地令牌属于
development
环境，因此访问受保护的生产环境需要配置
development
→ 
production
。
将此视为访问控制变更：先说明所需的确切规则，获得授权后再进行修改。不要扩大无关的环境配对范围。

Diagnose the response

诊断响应

  • A Vercel login, SSO, or Deployment Protection page means the request did not use an accepted authentication path.
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH
    means the token is valid but its caller environment is not allowed to reach the target environment.
  • An application-generated 
    401
    or 
    403
    after Vercel protection is bypassed belongs to the application's own authentication and must be debugged separately.
  • A deployment marked 
    "target": "production"
    can still be protected. Do not assume production is public.
  • 出现Vercel登录、SSO或Deployment Protection页面，说明请求未使用被接受的身份验证路径。
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH
    表示令牌有效，但调用者的环境不被允许访问目标环境。
  • 绕过Vercel保护后出现应用程序生成的
    401
    或
    403
    状态码，属于应用程序自身的身份验证问题，需单独调试。
  • 标记为
    "target": "production"
    的部署仍可能受保护，不要假设生产环境是公开的。

Avoid

注意事项

  • Do not disable Deployment Protection to make automation pass.
  • Do not send raw unauthenticated 
    curl
    repeatedly after receiving the protection page.
  • Do not start an interactive SSO browser login when 
    vc curl
    or an origin-scoped OIDC header can authenticate the request.
  • Do not expose 
    VERCEL_OIDC_TOKEN
    in logs, screenshots, committed files, or user-facing output.
  • 不要为了让自动化流程通过而禁用Deployment Protection。
  • 收到保护页面后，不要反复发送未认证的原生
    curl
    请求。
  • 当
    vc curl
    或源范围OIDC请求头可完成身份验证时，不要启动交互式SSO浏览器登录。
  • 不要在日志、截图、已提交文件或面向用户的输出中暴露
    VERCEL_OIDC_TOKEN
    。

Related skills

相关技能

  • General Vercel CLI usage: 
    ⤳ skill: vercel-cli
  • End-to-end application verification: 
    ⤳ skill: verification
  • Vercel CLI通用用法：
    ⤳ skill: vercel-cli
  • 端到端应用验证：
    ⤳ skill: verification