REST Client 环境变量必须抽离到 settings.json 和 .env：.http 文件仅引用 {{baseUrl}}/{{apiKey}}，通过脚本统一切换 NODE_ENV，避免硬编码导致 Git 冲突与 401 错误。
REST Client 的环境变量必须抽离到 settings.json + .env
团队协作时，硬编码 Base URL 和 API Key 在 .http 文件里是灾难源头：有人改了 Key 忘记同步，有人本地用 TaoToken、测试环境用 OpenAI，GET https://api.openai.com/v1/chat/completions 和 GET https://taotoken.net/api/v1/chat/completions 混在同一个项目里，Git 冲突频发，401 报错排查成本飙升。
正确做法是把所有可变参数外移：
-
settings.json（全局或工作区级）定义rest-client.environmentVariables，例如："rest-client.environmentVariables": { "local": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-xxx-local" }, "prod": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-xxx-prod" } } - 项目根目录放
.env文件，只写当前激活环境名：NODE_ENV=local
-
.http文件里只用变量引用：GET {{baseUrl}}/v1/chat/completions Authorization: Bearer {{apiKey}} Content-Type: application/json
注意：baseUrl 末尾不要加斜杠，否则拼接 /v1/... 会变成双斜杠；apiKey 值不能带空格或换行，否则请求头解析失败直接 400。
Swagger UI 必须由后端服务挂载，VSCode 不负责渲染
很多人误以为装个插件就能“在 VSCode 里打开 Swagger”，其实不是。VSCode 只能启动并调试后端服务，Swagger UI 是后端框架（如 FastAPI、Express）挂载的一个静态路由，比如 /docs 或 /api-docs。团队成员访问的地址必须一致，否则联调时看到的接口和实际调用的不匹配。
确保以下三点统一：
- 所有成员的
launch.json中port字段一致（如3000），且未被占用 - 后端代码中挂载 Swagger 的路径明确，FastAPI 默认是
/docs，Express +swagger-ui-express通常设为/api-docs - 团队约定文档访问地址，写进 README，例如：
http://localhost:3000/docs，禁止个人随意改路径
如果某人改了 app.use('/swagger', ...)，其他人按约定地址打不开，就会以为“Swagger 配置失败”，其实是路径不一致。
调试时断点不命中？先确认 Xdebug / Python 调试器是否真正连上
接口调试 ≠ 看响应结果，而是要能进到 Controller / Route 处理逻辑里单步执行。断点不命中，90% 是通信链路断在第一步。
PHP（Laravel）场景下检查顺序：
- 运行
php -m | grep xdebug，确认 Xdebug 已加载（不是phpinfo()里有就行，得真实启用） -
php.ini中xdebug.mode = debug且xdebug.start_with_request = yes（别用trigger_value，团队协作没法统一传 header） -
launch.json的port（如9003）必须和xdebug.client_port完全一致 - VSCode 的 PHP Debug 插件状态栏显示 “Xdebug listening” 才算就绪，没显示就说明监听没起来
Python（FastAPI）场景下常见坑：launch.json 里漏了 "justMyCode": false，导致断点进不到 uvicorn 启动逻辑；或者用了 --reload 但没配 console: "integratedTerminal"，热重载后调试器自动断开。
环境切换必须靠统一脚本或命令，不能手动改配置
团队里有人切 TaoToken，有人切本地 Ollama，有人还要连 Azure OpenAI——靠人肉改 settings.json 或 .env，不出三天就乱套。必须固化切换动作。
推荐方案：
- 在项目根目录加
scripts/env-switch.sh（macOS/Linux）或env-switch.bat（Windows），内容只是覆盖.env文件：echo "NODE_ENV=taotoken" > .env
- VSCode 任务配置
tasks.json，绑定快捷键一键切换："label": "Set Env: TaoToken", "command": "./scripts/env-switch.sh", "type": "shell"
- HTTP 请求文件顶部加注释说明适用环境：
# @env: taotoken # @desc: 调用 TaoToken 统一通道的 chat 接口
这个环节最容易被忽略的是「环境标识不可信」：没人会主动更新注释，所以必须让执行动作（脚本）成为唯一可信源，而不是靠人看注释判断。
