常见问题排查（FAQ）
按"症状 → 原因 → 怎么办"组织。连不上、鉴权失败、乱码、变量取不到是四大类。
连接 / 发送失败
| 症状 | 常见原因 | 解决 |
|---|---|---|
| 提示找不到基址 | 分组未绑环境，或环境缺该协议前置 URL | 绑环境、补对应协议的前置 URL |
| WS/gRPC/MQTT 连不上 | 前置 URL 的 scheme 写错（归类看 scheme） | ws 用 ws/wss、grpc 用 grpc/grpcs、mqtt 用 mqtt/mqtts |
| TCP/UDP 连不上 | 主机/端口填反了 | 主机填地址、端口单独填 |
| TLS 报错 | 加密 scheme 但没配证书 | 导入客户端证书，或按需关闭 TLS 校验 |
| 长连接突然断了 | 空闲自动回收 | 用完前重连；批量调试及时关旧会话（有配额上限） |
鉴权（401 / 403）
| 症状 | 原因 | 解决 |
|---|---|---|
| 带 Token 仍 401 | 前置脚本没跑（脚本执行被关） | 确认开启了"执行脚本" |
{{authToken}} 原样保留（没被替换） | {{}} 读不到运行期存的 Token | 改用前置脚本 sdk.env.get 注入头（见 recipes 场景1） |
| 登录后下一个请求取不到 Token | 两个请求不在同组/不同环境 | 让它们同组、绑同一环境（运行期变量按环境隔离） |
乱码 / 编码
| 症状 | 原因 | 解决 |
|---|---|---|
| 中文响应乱码 | 服务端返回非 UTF-8（如 GBK） | 用对应字符集解码；测试端点 /charset/gbk 可复现 |
解密拿到 Error: ... 字符串 | 密文非法/为空，或 key/iv 与加密时不一致（$crypto 失败只返错误串、不会抛异常/中断） | 保证加/解密 key/iv 一致； 判成败看返回串是否以 Error: 开头（中文明文实测可正常往返） |
脚本报 Script aborted request | 脚本里有未被 try/catch 捕获的 JS 异常（常见：headers.set 写了非 ASCII 头值、或对 undefined 取属性） | 给 risky 调用包 try/catch；UTF-8 内容放 body/查询参数，头值保持 ASCII |
| 脚本里 base64 结果怪 | 给 $codec/sdk.utils 传了 Uint8Array/字节（会被 String() 成 "97,98,99" 再编码） | 一律传字符串；$codec.base64Encode/Decode 与 sdk.utils.base64Encode/Decode 都是 UTF-8 感知的字符串↔字符串，二选一 |
脚本没生效
| 症状 | 原因 | 解决 |
|---|---|---|
| 前置脚本改了 body 但线上没变 | 没"赋值"改写 | request.body = 新字符串（赋值整体替换） |
| 后置改写响应看不到 | 改写方式 | response.body = 新字符串；改写后界面/返回显示的就是新内容 |
| 脚本报"无入口跳过" | 函数名不对 | 必须叫 onRequest / onResponse |
| 多条脚本取不到彼此的值 | 不了解共享机制 | 同一条链的脚本共享 globalThis，用 globalThis.xxx 传递 |
| 脚本里 AES 报加密失败 | 参数形态错 | $crypto.encryptAES 用位置参数字符串，不要传 对象 {text,key,iv} |
脚本报 require: 未找到库 [...] | 引用键写错，或用户脚本库被重命名/删除 | 从库管理列表复制 require 语句（identifier 形态不受重命名影响）；内置库键为 @libs/base64 / @libs/hex；注释里的 require 不参与解析、不会打包 |
变量取值对照
{{名字}}：只取环境配置类变量 / 逐次发送变量，取不到运行期脚本存的值。- 脚本里读变量：三层都能读到，跨请求传 Token 用它。
- 想让提取值也能被
{{}}用：开启"提取回写环境"设置。
详见 concepts 变量体系。
还是搞不定？
- 先用
/echo（HTTP）、/ws/echo（WS）把"最小能通"跑起来，再逐步加认证/脚本。 - 一步步定位：请求能否发出（连不通→查前置 URL/主机端口）→ 脚本是否执行（开没开脚本）→ 变量是否命中（哪一层）。
- 涉及脚本的报错可对照脚本 API 参考排查。