PhpStorm调试RESTful API接口的完整流程-phpstorm-PHP中文网

phpstorm http client 发不出请求的四个硬性条件：文件必须是项目内的 .http 或 .rest 文件且首行严格为“方法 url”；变量名仅支持字母数字下划线、需先定义后引用；调试 php 必须显式添加 xdebug_session_start: phpstorm 请求头；环境变量须通过项目根目录下的 .rest-client.env.json 正确配置。

phpstorm调试restful api接口的完整流程

PhpStorm HTTP Client 发不出请求？先盯死这四个硬性条件

根本发不出请求，不是插件没装、也不是网络问题，大概率是文件没被识别。PhpStorm 的 HTTP Client 只扫描项目内后缀为 .http 或 .rest 的纯文本文件，且仅当首行严格匹配“大写方法 + 空格 + 完整 URL”时才激活。

常见失效现象：Cannot resolve variable、光标停在首行无绿色甲虫图标、按 Ctrl+Enter 没反应、响应窗口空白。

文件必须放在 PhpStorm 打开的项目根目录或其任意子目录下——放桌面、/tmp、或未被索引的外部路径，一律无效
首行顶格写，不能有空格、注释、中文、URL 编码缺失（如 GET https://api.com/users?name=张三 必须写成 GET https://api.com/users?name=%E5%BC%A0%E4%B8%89）
变量名只允许字母、数字、下划线；api.base_url、auth-token 这类含点或短横的写法直接报错
变量必须先定义后引用：定义在顶部全局生效，或用 ### 分隔块内定义——但块内定义对块外请求不可见

调试 PHP 接口必须加 `XDEBUG_SESSION_START: PHPSTORM` 头

没有这个头，Xdebug 不会尝试连接 PhpStorm，断点永远不触发。这不是可选配置，是硬性开关。

常见错误：以为开了 Xdebug 就自动连、在 php.ini 里配了 xdebug.start_with_request=trigger 就够了、或者只在 Postman 里加了却忘了在 .http 文件里显式写。

头必须写在请求体上方的 headers 区域，格式为：XDEBUG_SESSION_START: PHPSTORM（注意冒号后有空格）
不能写成 XDEBUG_SESSION_START=PHPSTORM 或 xdebug_session_start: phpstorm（大小写敏感、等号非法）
如果用环境变量（如 {{host}}），确保变量值不含尾部斜杠，否则拼出的 URL 可能变成 http://localhost:8000//api/users，导致路由匹配失败
调试前确认 PhpStorm 已启动监听：右下角状态栏应显示 Debug listening...，否则点击 Run → Start Listening for PHP Debug Connections

POST 请求体 JSON 顶格写，别缩进、别空行、别带 BOM

JSON body 不是“看起来像就行”，HTTP Client 对格式极其敏感。一个不可见字符就让服务端返回 400 Bad Request 或直接解析失败。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

常见错误：从 VSCode 或网页复制 JSON、用 IDE 自动格式化插入缩进、保存为 UTF-8 with BOM、body 前多了一个空行。

body 必须紧接空行之后，第一行就是 { 或 [，不能有任何前置空格或换行
用 Content-Type: application/json 头，别漏掉
中文字段值无需手动编码——JSON 标准支持 UTF-8，只要文件本身保存为 UTF-8 without BOM 即可
如果 body 含变量（如 {{user_data}}），确保该变量值本身就是合法 JSON 字符串，而不是 PHP 数组或未 json_encode() 的原始数据

变量跨文件/跨环境失效？检查 `.rest-client.env.json` 路径和字段名

用 .rest-client.env.json 管理环境变量很省事，但 PhpStorm 只在项目根目录找它——放错位置或字段名不一致，变量就静默失效，连报错都没有。

典型表现：请求发出去了，但 URL 是 https://{{base_url}}/api 这种原始字符串，或日志里只有一句 Cannot resolve variable 'base_url'。

文件名必须是 .rest-client.env.json（注意开头的点，不是 http-client.env.json）
必须放在项目根目录，不能在 src/ 或 config/ 下；若非要放别处，需手动在 Settings → Tools → HTTP Client → Environment files 中指定路径
JSON 字段名必须与 {{xxx}} 中的 xxx 完全一致，包括大小写和下划线；"base_url": "https://dev.api.com" 对应 {{base_url}}，不能写成 {{baseUrl}} 或 {{BASE_URL}}
JSON 值只能是字符串、布尔或数字；不能嵌套对象或数组，否则变量解析失败

最易被忽略的点：变量作用域是静态的、基于文件结构的。你在某个 ### 块里定义的 @token = xxx，不会泄露到上一个块或全局；而 .rest-client.env.json 里的变量，又无法在 .http 文件里用 @ 语法覆盖——它们是两套独立系统，混用前务必看清文档边界。