OAuth 2.0 配置必须严格定义在项目根目录的 env.json 文件中，嵌套于 "Security": {"Auth": {...}} 路径下，变量名禁用点号和短横线，Grant Type 为 Authorization Code 时 Auth URL 和 Token URL 必须含完整协议；调用 $auth.token("my-oauth") 前需确保 JCEF 浏览器可弹出，Authorization 头须写为 Bearer {{$auth.token("my-oauth")}}（含空格及双大括号），调试应优先查看 Authentication Log。
OAuth 2.0 配置必须写在 env.json 里，不能直接塞进 .http 文件
很多人试图在 .http 文件里硬编码 Authorization: Bearer xxx 或手拼 token URL，结果每次换环境都要改请求——这既不安全也不可持续。PhpStorm 的 OAuth 支持依赖统一的环境配置文件，所有认证参数必须定义在项目根目录的 env.json 中，否则 $auth.token() 变量根本无法解析。
关键点：
-
env.json必须放在项目最外层目录，且文件名严格为env.json（不是.env.json或environments.json） - 变量名禁用点号和短横线，比如
oauth.client-id会失败，得写成oauth_client_id - OAuth 配置块必须嵌套在
"Security": {"Auth": {...}}路径下，大小写敏感（Type不是type） - Grant Type 选
Authorization Code时，Auth URL和Token URL必须带完整协议+域名，比如https://auth.example.com/oauth/authorize，少一个https://就静默失败
调用 $auth.token("my-oauth") 前，先确认 JCEF 浏览器能弹出来
点击运行带 $auth.token("my-oauth") 的请求后，如果 IDE 没弹出登录窗口，不是配置错了，而是 JCEF 浏览器被系统策略或代理拦截了。这不是 PhpStorm 的 bug，而是底层 Chromium 组件的限制。
常见卡点：
立即学习“PHP免费学习笔记（深入）”；
- 公司内网常禁用非 Chrome 浏览器的 UA，JCEF 默认 UA 是
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36，可临时在Help → Edit Custom Properties里加一行ide.browser.jcef.user.agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 - Docker 或 WSL2 环境下，JCEF 无法访问宿主机的 X11 或 Wayland，此时必须切到
Mock模式手动填 token，别硬等弹窗 - 第一次弹窗后若输错密码，后续再运行仍会复用失败缓存；需去
Services → HTTP Client → Authentication Log点右上角刷新图标清空状态
Authorization 头里写 Bearer {{$auth.token("my-oauth")}}，别漏空格和大括号
这是最常复制粘贴出错的地方：Bearer{{$auth.token("my-oauth")}}（没空格）或 Bearer $auth.token("my-oauth")（少大括号）都会导致服务端返回 401 Invalid token format。PhpStorm 的变量插值只认双大括号语法，且 Bearer 和 token 之间必须有且仅有一个空格。
正确写法示例：
GET {{api_base_url}}/user/profile
Authorization: Bearer {{$auth.token("google-oauth")}}
Accept: application/json
注意：
- 不要在
Authorization头里混用其他字段，比如Authorization: Bearer {{$auth.token(...)}}; foo=bar—— 这会被当整个字符串传给服务端 - 如果 API 要求
Authorization: Basic xxx+ OAuth token 双重校验，得拆成两个头：Authorization: Basic ...和X-OAuth-Token: {{$auth.token(...)}} - token 实际注入发生在发送瞬间，调试时看
Services → HTTP Client → Request History里的原始请求，才能确认 header 是否真被替换了
调试失败时，优先查 Authentication Log 而不是网络抓包
当你看到 400 Bad Request 或 401 Unauthorized，第一反应不该是开 Charles 或 Wireshark，而应打开 Services → HTTP Client → Authentication Log。这里记录了从跳转 URL、code exchange 请求体、到最终 access_token 的全过程，比任何外部工具都贴近 PhpStorm 的真实行为。
典型日志线索：
- 出现
Failed to parse JSON response from token endpoint：说明Token URL返回的不是标准 OAuth 2.0 JSON（比如少了access_token字段，或用了data.token包裹） - 日志停在
Redirecting to auth URL...就不动：JCEF 页面加载失败，检查控制台是否有 CSP 报错，或换用Mock模式绕过 - token 获取成功但请求仍 401：大概率是服务端校验了
audience或resource，需在 env.json 的 OAuth 配置里补上"audience": "https://api.example.com"
真正麻烦的不是配置步骤，而是 OAuth 流程中任意一环（浏览器、重定向、token 解析、header 注入）都可能 silently fail，且错误信息藏得深。盯住 Authentication Log，比反复改 .http 文件高效得多。
