6步修复 Stash 配置文件无效：从订阅到 YAML 校验
简答：Stash 配置文件无效时，先按报错时机定位，再检查订阅响应和 YAML 结构；用最小配置、错误对照与 Override 回退逐项恢复，最后查看日志确认。
定义：“配置文件无效”是 Stash 无法解析、保存、激活或启动主配置、订阅配置或 Override 覆写文件的统称，不一定只代表 YAML 语法错误。
先看报错时机：10秒找到排查入口
先不要反复导入，也不要覆盖唯一配置副本。Stash 的配置由主配置文件和可选的 Override 组成，Override 优先级高于主配置；官方文档还说明，配置文件采用 YAML，缩进会影响结构。查看 Stash 配置样例与 Override 关系
| 报错时机 | 优先怀疑 | 第一步 |
|---|---|---|
| 下载或导入后立刻无效 | 订阅返回 HTML、登录页、JSON、空内容、Base64 或其他格式 | 保存响应正文，查看状态码和首行 |
| 编辑后保存失败 | 缩进、Tab、冒号、引号、列表或重复键 | 按行号检查 YAML 结构 |
| 可以导入但无法激活 | 代理组引用、字段格式或 Override 冲突 | 停用全部 Override 后重试 |
| 启动后立即异常 | 版本兼容、协议参数或特定配置字段 | 用最小配置区分语法与运行问题 |
官方快速上手说明中，远程配置入口大致位于“设置→配置文件→从 URL 下载”，导入后还要确认目标配置已选中，再返回首页启动；菜单名称以当前版本为准。查看 Stash 快速上手步骤
先备份，再确认订阅返回的到底是什么
修改前记录原配置名称、订阅地址、已启用的 Override、DNS、MTU、代理模式和节点选择。随后把旧配置复制一份，避免排查过程中无法回退。
订阅服务端可能根据 User-Agent、请求头、登录状态或订阅参数返回不同内容，因此普通 curl 的结果不一定等于 Stash 实际收到的内容。可以先做两次对照：
curl -L -D headers.txt -o response.txt "订阅URL"
curl -L -A "Stash" -D stash-headers.txt -o stash-response.txt "订阅URL"这里的 Stash 只是示例 User-Agent，服务端可能要求包含客户端名称或版本信息。若 Stash 的最近请求、日志或请求头页面能看到实际请求头，应优先按实际值测试。不要把包含订阅密钥的完整地址提交给陌生网站或公开粘贴。
| 返回内容 | 常见原因 | 处理方式 |
|---|---|---|
| HTML 或登录页 | 链接失效、需要登录、发生重定向 | 检查最终状态码、登录状态和订阅有效期 |
| JSON | 接口返回错误信息或管理接口响应 | 读取错误字段，不要直接当作 Stash 配置导入 |
| 空内容 | 鉴权失败、服务端异常或链接过期 | 对照 User-Agent、请求头和订阅状态 |
| 一长串无空格字符 | 可能是 Base64 节点列表或其他订阅格式 | 确认服务端是否提供 Stash/Clash YAML 格式 |
| 看似 YAML 但字段很少 | 服务端返回了不完整配置或转换失败 | 保存原文并核对是否包含实际代理、策略组和规则 |
Stash 官方文档说明，远程配置应通过 URL 下载并在配置列表中选中；如果响应正文不是目标格式，反复点击导入通常无法解决。参考官方远程配置导入说明
复制可用的最小 YAML：先区分语法错误与引用错误
官方配置样例说明，配置文件字段具有默认值，因此可以只保留需要修改的字段。下面第一份配置用于验证文件是否能被解析；第二份进一步加入 DIRECT 策略组和 MATCH 规则，用于检查基本引用关系。它们都不包含真实代理节点，不能单独提供代理连接。
# 仅验证 YAML 解析
mode: rule
log-level: info# 验证基础策略组与规则引用
mode: rule
log-level: info
proxy-groups:
- name: Auto
type: select
proxies:
- DIRECT
rules:
- MATCH,Auto如果第一份可以导入，第二份无法激活，问题就不再只是 YAML 基础语法，还应检查策略组、规则和代理名称之间的引用关系。若第二份也能激活，而原订阅不能，优先回到订阅内容、协议字段或 Override 排查。
| 错误写法 | 原因 | 修正写法 |
|---|---|---|
| 键和值之间缺少冒号 | |
| 冒号后没有空格时，常被当作普通字符串，根节点不是键值映射 | |
| 列表层级不清晰，容易与父级结构混淆 | |
| 嵌套列表没有保持一致缩进 | |
| 重复键会造成覆盖或被校验器拒绝，不能依赖最后一行生效 | |
编辑时只使用空格，不要混用 Tab。包含 #、冒号、正则表达式或特殊符号的值，必要时使用引号。found character that cannot start、mapping values are not allowed 等属于常见 YAML 解析报错，Stash 界面提示可能不同，不应直接当作 Stash 固定原文。官方配置文档建议使用 YAML 校验工具检查格式，也可以使用本地校验方式避免泄露敏感信息。查看官方 YAML 配置说明
按行号定位 YAML：从报错行向上查父级
如果校验器指出第 N 行，先在编辑器中打开行号显示，再检查该行及其上方最近的父级键。YAML 错误经常出现在报错行的上一层：例如列表少了短横线、父级缩进多了一个空格，真正问题可能不在提示行本身。
- 从报错行向上查看最近的键，例如
dns:、proxy-groups:或rules:。 - 确认同一层级使用相同数量的空格，列表项目都以
-开始。 - 搜索整份文件中的重复键，例如两个
mode:、两个proxies:或两个rules:。 - 打开编辑器的显示空白字符功能，查找 Tab、全角空格和不可见字符。
- 先删除最近新增的一个字段，再校验；不要一次改动多个区域。
出现引号未闭合时，从出错行向前寻找最近的单引号或双引号；出现冒号相关错误时，检查值中是否含有冒号但没有用引号包裹。校验通过后，再回到 Stash 导入，不要把“能通过通用 YAML 校验”误认为“所有 Stash 字段都兼容”。
停用 Override，再检查字段与协议兼容性
Stash 配置由主配置和 Override 共同组成，官方文档明确说明 Override 中的字段会覆盖主配置中的字段。因此主配置单独看起来正确，最终启用结果仍可能无效。
- 复制主配置和全部 Override，保留原文件与原值。
- 只启用主配置，暂时停用全部 Override。
- 确认主配置可以导入、激活并启动。
- 每次只恢复一个 Override，恢复后立即测试。
- 定位问题后，检查其中引用的策略组名称、代理名称、规则字段和缩进。
协议字段、服务商自定义字段和内核参数可能受当前版本支持范围影响。查不到官方说明的字段或参数，应标记为“未核实”，不要直接照抄其他客户端配置。Stash 的 macOS 更新记录显示，4.2.0 包含配置文件可视化编辑、覆写可视化编辑和“最近请求”页面优化；这些功能与入口不能默认推定适用于所有平台或版本，应以当前版本为准。查看 Stash macOS 更新记录中的对应功能
| 错误关键词或表现 | 常见原因 | 处理方式 |
|---|---|---|
| found character that cannot start | Tab、不可见字符、列表符号或引号结构异常 | 显示空白字符，统一改为空格并重新校验 |
| mapping values are not allowed | 冒号、缩进或多行值结构错误 | 从报错行向上检查父级键和值的层级 |
| 重复键 | 同一层级重复定义字段 | 搜索同名键，只保留一份并记录原值 |
| 导入后为空 | HTML、JSON、空响应、Base64 或非目标订阅格式 | 用带 User-Agent 的命令保存正文并确认格式 |
| 能导入但无法启动 | 策略组引用不存在、协议字段不兼容或 Override 冲突 | 停用 Override，再用最小引用配置测试 |
iOS、macOS、tvOS 的日志与授权排查
Stash 官方资料显示，它覆盖 iOS、tvOS、macOS 等 Apple 平台；具体菜单以当前版本为准。查看 Stash 平台范围说明
| 平台 | 优先检查 | 日志、导出与授权 |
|---|---|---|
| iOS | 远程 URL、本地文件、当前选中的配置和 Override | 在当前版本的日志或最近请求入口查看错误；复制错误时间、配置名称和响应信息，按系统提示完成网络扩展授权 |
| macOS | 配置文件可视化编辑器、最近请求、请求头和订阅响应 | 在“最近请求”页面查看总览、日志和请求头；若提供导出或复制按钮，保存后打码敏感信息。Helper、TUN 等权限以系统提示为准 |
| tvOS | 远程配置是否可下载、配置是否选中、基础字段是否能解析 | 按当前版本界面查看日志；需要网络或系统授权时完成系统提示，无法操作时先用最小配置测试 |
提交问题时，建议同时提供：错误原文、发生时间、配置名称、导入方式、HTTP 状态、日志片段、请求头信息和是否启用 Override。导出或复制前删除订阅密钥、节点地址、账号、Cookie 和本地网络信息。若界面没有导出功能，可复制相关日志文本或截图，但不要只提交“配置文件无效”这一句。
最后按这个顺序恢复，避免越改越乱
- 记录原配置、订阅地址、Override、DNS、MTU、代理模式和节点选择。
- 复制旧文件，保留一份不可修改的备份。
- 用最小 YAML 验证 Stash 是否能解析文件。
- 用已确认返回 YAML 的配置测试导入和激活。
- 先恢复主配置，再恢复策略组、规则、DNS、脚本和协议参数。
- 最后逐个恢复 Override，每次只改一组字段并记录结果。
如果多网络、多设备对照后，其他网站正常，只有目标服务持续变慢或丢包，再进行 DNS、MTU、延迟和丢包的网络层排查；不要通过改变地区来规避限制。
常见问题
Stash 配置文件无效，最先应该检查什么？
先备份原配置，再确认导入来源返回的是有效 Stash/Clash YAML，而不是 HTML、登录页、JSON、空内容、Base64 或其他订阅格式。
最小 YAML 配置能直接使用代理吗？
不能。最小配置只能验证解析和基础引用，示例中没有真实代理节点、完整策略组和分流规则，不能单独提供代理连接。
为什么 curl 能看到内容，但 Stash 仍然提示无效？
订阅服务端可能按 User-Agent、请求头、登录状态或参数返回不同内容。应使用接近 Stash 实际请求头的方式重新对照。
为什么 mode:rule 会导致配置无效？
冒号后没有空格时，它可能被解析成普通字符串，而不是键值映射；应改为 mode: rule，并重新检查根节点结构。
如何判断是不是重复键造成的问题？
在编辑器中搜索同名字段，例如 mode、proxies 或 rules，确认同一层级只保留一份，并记录删除前的原值。
主配置没有错误，为什么启用 Override 后仍然无效？
Override 会覆盖主配置。建议停用全部 Override，先确认主配置能激活，再逐个恢复以定位冲突文件。
通用 YAML 校验通过后，为什么 Stash 仍可能无法启动？
YAML 校验只能说明语法基本可解析，不能保证策略组引用、协议字段、服务商字段和当前 Stash 版本都兼容。
Stash 的日志应该提交哪些内容？
提交错误原文、发生时间、配置名称、响应状态、日志、请求头和启用的 Override；先删除订阅密钥、节点地址、账号和 Cookie。