Stash 配置文件格式错误怎么解决：YAML 排查与修复步骤
简答：先不要反复导入同一份文件：Stash 配置文件格式错误，优先检查 YAML 缩进和特殊字符，再确认文件内容不是 HTML 或 JSON，最后排查字段与版本兼容。本文给出一套从最小配置开始恢复的步骤，适用于 iOS、macOS 和 tvOS。
定义：Stash 配置文件是使用 YAML 编写的文本配置，主配置负责基础字段，覆写配置可在其上覆盖部分字段，二者都必须先通过 YAML 解析。
先按现象判断：语法、字段还是内容异常
本站是第三方信息页，不是 Stash 官网，与 Stash 无已核实关系。先看报错出现在哪一步，再决定是否修改内容；不要一看到“格式错误”就直接重写整份配置。
| 现象 | 优先怀疑 | 先做什么 |
|---|---|---|
| 导入后立即提示 line、column 或缩进错误 | YAML 语法、Tab、冒号或引号 | 复制到 YAML 校验工具检查行列位置 |
| 能打开文件，但提示字段缺失或配置无效 | 键名、层级或 mode 写法不符合识别要求 | 与配置样例逐项对照 |
| 文件下载成功，却显示网页或 JSON 内容 | 远程地址返回错误页、登录页或接口提示 | 用文本编辑器查看文件开头和响应类型 |
| 旧文件可用，新版本导入失败 | 版本兼容或某字段行为变化 | 查看对应系统的更新记录，并先回退到最小配置 |
如果提示包含“line 12 column 5”之类的位置，先修复该行附近的结构问题；如果没有行列信息而是字段不识别，则优先检查字段名和层级。
第一步：用最小配置确认基础解析是否正常
先另存为一份新文件，不要直接覆盖原文件。使用空格缩进，不使用 Tab；配置文件使用 UTF-8 保存，扩展名保持为 .yaml 或应用能够识别的配置格式。
mode: rule
log-level: info这份配置只用于判断基础 YAML 和核心字段能否被读取，不代表完整业务配置。Stash 用户文档说明，配置文件采用 YAML，缩进会影响整体结构，并且不是每个字段都必须手动填写；因此，先用最少字段验证，再逐段添加内容更容易定位问题。
导入步骤以应用当前界面为准：在配置文件列表中导入本地文件或从 URL 下载，选中该文件后返回首页启动。相关流程可参考Stash 快速上手文档。
第二步：修复最容易出错的 YAML 写法
以下示例中的“错误”有些会直接报语法错误，有些可能仍能被 YAML 解析，但不会形成应用需要的键值结构。
| 问题 | 容易写成 | 建议写法 |
|---|---|---|
| 键和值缺少空格 | mode:rule | mode: rule |
| 使用 Tab 缩进 | http:下一行用 Tab | 改为两个或四个空格，并保持全文件一致 |
| 冒号后没有空格 | name:office | name: office |
| 井号被误当作普通字符 | name: office #1 | name: 'office #1' |
| 正则或特殊字符未加引号 | pattern: ^https?://a\.example | pattern: '^https?://a\.example' |
| 列表层级不一致 | - one与下一级错位 | 每个列表项保持同一缩进层级 |
特别注意：mode:rule不一定直接报 YAML 语法错，它可能被解析成一段普通字符串，最终表现为没有识别到正确的键值对。name: office#1则通常会被解析成字符串“office#1”，并不是因为井号紧贴文字就必然错误；如果希望名称确实包含“#1”，应使用引号。
含反斜杠、问号、井号、星号、短横线或冒号的字符串，优先使用单引号包裹。若字符串本身包含单引号，再改用双引号并正确转义。
第三步：检查缩进、列表和路由模式
YAML 的层级由缩进表示。下面的结构中，rules 下的每一项必须处于同一层级：
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- DOMAIN-SUFFIX,example.org,SELECT不要把同一组内容一部分写成列表，一部分写成普通文本。对路由模式，可按以下含义选择：
| 模式 | 作用 | 适用场景 |
|---|---|---|
rule | 按规则将不同请求分流 | 日常使用，希望不同业务按既有规则处理 |
global | 全部流量走当前选定线路 | 临时验证某条线路或排查规则是否导致异常 |
direct | 全部直连，不使用配置中的线路 | 确认问题是否来自线路、规则或解析链路 |
排查结束后，应切回日常需要的模式。模式切换只能帮助定位问题，不能修复缩进、字段缺失或远程内容错误。
第四步：确认下载到的确实是 YAML 配置
如果本地校验没有明显语法错误，但 Stash 仍提示格式错误，检查文件实际内容。用文本编辑器打开后，文件开头通常应能看到配置键名，例如 mode:、log-level: 或其他配置字段。
- 如果开头是
<html>、<!DOCTYPE，通常说明下载到的是网页或错误页。 - 如果内容是带大括号的 JSON，例如
{"data": ...}，它不等于 YAML 配置，不能仅靠修改扩展名解决。 - 如果文件只有一行提示文字、登录提示或接口错误信息，应回到提供配置的页面重新获取地址。
- 检查文件是否为空、是否被截断，以及是否混入不可见字符、BOM 或异常换行。
远程配置重新导入时，先删除或停用当前异常文件，再重新下载并选中新的文件；本地文件则重新保存后再导入。官方快速上手文档列出了从 URL 下载和从 iCloud、OneDrive 或 AirDrop 导入本地文件的路径，具体菜单名称以当前版本界面为准。
第五步：区分字段错误、参数错误和版本兼容
通过 YAML 校验，只能说明文本结构基本可解析，不能证明所有字段都被当前版本支持。可以按以下顺序处理：
- 保留最小配置，确认文件能被导入。
- 一次只加入一个区块，例如日志、端口、线路、规则或策略组。
- 每加入一个区块就重新校验并导入，记录最后一次成功的版本。
- 如果某个区块单独加入后失败，检查字段拼写、缩进、值的类型以及当前系统版本支持情况。
- 如果旧配置在某版本可用、新版本失败，先查看对应系统更新记录，再决定是否升级、回退或删除不兼容字段。
截至 2026 年 10 月 25 日，公开更新记录中，tvOS 页面列出 2.6.6 曾修复 YAML 空格导致的配置识别问题；较新的 3.3.3 更新记录还包含配置相关功能和问题修复。版本行为可能随系统和应用版本变化，具体以tvOS 更新记录及对应平台页面为准。
macOS 用户如果遇到本地文件重新载入或可视化编辑入口变化，应以当前应用界面为准，并保留一份原始配置作为回退副本。可参考macOS 更新记录核对版本变化。
修复后怎么验证，避免再次误判
修复完成后，不要只看文件能否导入，还要验证配置是否真正生效：
- 先导入最小配置，确认应用可以选中并启动。
- 逐段恢复原配置，每次只加入一组字段。
- 遇到报错时，保留报错行号和最近一次加入的内容。
- 确认路由模式、线路选择和规则结果符合预期。
- 完成排查后，删除不再使用的测试文件，避免下次误选旧配置。
如果配置中包含访问凭据、UUID、密码或远程地址，提交给他人协助前应先打码；不要把完整配置文件、二维码或远程地址直接公开。
如果你还要排查设备间连接或办公网络，可继续阅读手机电脑同时使用时的连接排查清单、跨境办公网络的分流与验收方法，以及按延迟和丢包判断线路稳定性的方法。
常见问题
Stash 配置文件格式错误，最先检查什么？
先检查是否使用空格而不是 Tab、冒号后是否有空格、缩进层级是否一致，再用 YAML 校验工具查看具体行列。
mode:rule 为什么可能不报语法错误？
它可能被 YAML 当作普通字符串解析，而不是由 mode 和 rule 组成的键值对，所以最终表现为字段缺失或模式没有生效。建议改成 mode: rule。
name: office#1 一定是错误写法吗？
不一定。井号前没有空格时，通常会作为字符串内容解析；如果希望明确保留“#1”，建议写成 name: 'office #1'。
为什么校验通过，Stash 仍然提示配置无效？
YAML 校验只代表文本结构基本正确，不能保证字段名称、字段类型和当前版本都支持。应使用最小配置，再逐组恢复字段。
如何判断下载到的不是配置文件？
用文本编辑器查看开头。如果出现 HTML 标签、登录页面、接口错误文字或 JSON 对象，说明返回内容不是可直接使用的 YAML 配置，需要重新获取正确的远程地址。
修改配置前需要备份吗？
需要。先复制原文件并保留最后一份可用版本，新增字段时一次只改一组，便于出现错误后快速回退。