Clash 与 Sing-box 客户端无法导入配置，90% 缘于 YAML 缩进对齐错误、单双引号未闭合或 Base64 编码中夹杂非法换行符。推荐优先使用本地格式检测工具进行静态语法校验，避免将包含凭证的敏感订阅泄露给不可信的第三方解析站。
- 零隐私泄露：纯本地浏览器离线校验，无需上传配置文件，彻底杜绝订阅 Token 与服务器 IP 外泄
- 语法即时标红：精准指出 YAML 缩进空格数差异与 JSON 缺失逗号的具体行号，一键快速定位
- 多格式互转：自动识别 Clash YAML、Sing-box JSON 与 V2Ray Base64 节点串并格式化输出
- 仅能校验语法结构合规性，无法探测远程服务器节点是否真实存活或可用
- 特殊自定义私有扩展字段可能被通用 YAML 校验器判定为语法警告
1YAML 与 JSON 配置文件三大致命语法陷阱
配置文件的解析失败多由肉眼极难察觉的空格与缩进问题引起。
Clash 采用严格的 YAML 语法规范：严禁使用 Tab 制表符，必须统一使用 2 个标准空格作为层级缩进；冒号后面必须保留至少 1 个半角空格（例如 port: 7890 合法，而 port:7890 会直接崩溃）。
Sing-box 则采用严谨的 JSON 结构，最后一个对象属性末尾严禁多余的逗号，键名必须包含标准双引号。客户端配置细节可参考站内 Clash Verge Rev 与 Sing-box 配置实战。
| 配置格式 | 常见报错代码 | 核心排查手法 | 适用客户端 |
|---|---|---|---|
| YAML | mapping values are not allowed here | 检查冒号后是否缺失空格或误用 Tab | Clash Verge Rev / OpenClash |
| JSON | invalid character '}' looking for beginning | 检查数组或对象末尾是否存在多余逗号 | Sing-box / SagerNet |
| Base64 | illegal base64 data at input byte | 检查结尾是否缺失 = 填充符或含有换行 | Shadowrocket / v2rayN |
2官方推荐语法校验与在线 Lint 工具
在导入客户端前，可将配置文本粘贴到权威 Lint 工具中进行一键自检与格式化对齐。
推荐使用国际权威开源的语法校验服务进行快速语法纠错：
业界权威开源 YAML 语法解析器，精准定位缩进层级与语法报错行号。
JSON 格式化与合规校验标准工具，支持一键美化对齐与语法修复。
格式校验通过后，可前往 订阅链接导入客户端配置指南 了解客户端导入规范。
3Base64 订阅链接解码与字符补齐规范
部分机场导出的原生节点链接以 Base64 编码提供，解码时需注意填充位。
Base64 字符串的长度必须为 4 的倍数。若复制时遗漏末尾的 = 补位符，解码器会抛出 padding error 异常。遇到无法导入时，可尝试在末尾补齐 1~2 个 = 后重新尝试。
若节点导入后依然报错连接超时，可前往 全链路连接故障排查中心 进行网络诊断。
4终端命令行极速语法自检与批量排错脚本
不依赖外部网页，在本地终端使用 Python 或 yq 几秒钟内定位数十万行配置文件的语法错误行号。
当配置文件体积达到数十万行（包含大量代理节点与 GeoIP/GeoSite 规则集）时，将内容直接复制到在线网页工具中极易发生浏览器卡死或剪贴板字符截断。此时使用本地终端进行快速语法排错是最高效的手段。
在 Windows（PowerShell / CMD）或 macOS 终端中，无需安装额外第三方软件，借助系统内置的 Python 解释器即可执行一行命令秒级测试语法：
python -c "import yaml, sys; yaml.safe_load(open('config.yaml', encoding='utf-8')); print('已通过 YAML 语法校验通过，结构完好！')"若配置文件存在语法缩进错误或未知非法字符，终端将立刻打印出 ScannerError 或 ParserError，并直接指出引发错误的确切行号（line）与列号（column），无需逐行人工排查。
编码避坑指南：在 Windows 下使用记事本等编辑器保存配置文件时，可能会自动附加「UTF-8 with BOM」签名头（十六进制 EF BB BF），这会导致 Clash 与 Sing-box 核心在启动时报 yaml: control characters are not allowed。请务必使用 VS Code 等专业代码编辑器将文件编码显式指定为标准的 UTF-8（无 BOM）。
| 校验工具 / 方案 | 适用场景 | 检测速度 | 优势与局限 |
|---|---|---|---|
| Python 内置 yaml 模块 | 大体积 config.yaml 排错 | < 0.5 秒 | 本地离线、隐私安全，精准打印报错行列号 |
| Node.js json.tool | Sing-box config.json 排错 | < 0.2 秒 | 内置快速高亮未闭合括号与多余逗号 |
| VS Code 插件 (YAML Lint) | 日常编写与可视化分流规则修改 | 实时波浪线报错 | 自动补全键值对，具备强大的 Schema 约束校验 |
| 在线校验站点 (YAML-Lint) | 临时小片段节点代码核对 | 受网络波动影响 | 便捷直观，但有敏感节点 URL 泄露风险 |
常见问题排查与解答 (FAQ)
收录真实使用环境中的高频疑问、错误代码速查与可执行修复脚本，已预设折叠排版。
1修改 YAML 配置文件后启动提示 mapping values are not allowed here 报错怎么办？
终端快速格式自检：可通过 Python 内置 yaml 模块在本地校验配置文件的语法合法性：
python -c "import yaml; yaml.safe_load(open('config.yaml', encoding='utf-8'))"2Sing-box 导入 JSON 提示 invalid character '}' looking for beginning of object key string？
"port": 443, }），删掉最后一个多余的逗号即可正常启动。