Stash 配置教程:导入、YAML、Override 与报错排查
简答:Stash 配置先导入兼容的 Clash/Stash 订阅或本地 YAML,选中后启动;需要自定义时用 .stoverride 覆写,再通过连接记录核对规则命中、DNS、出口 IP 和流量状态。
定义:Stash 配置是由 YAML 主配置文件、可选的 .stoverride 覆写文件,以及代理、策略组、DNS 和分流规则共同组成的网络配置。
先试这一步:导入后确认配置、节点、规则和出口
如果你的目标只是先让 Stash 运行,不必马上手写完整配置。准备一条服务提供方给出的兼容订阅地址,或一份本地 Stash/Clash YAML,然后按Stash 官方快速上手文档导入。订阅链接通常包含账号凭证,不要公开发布,也不要提交到无法确认用途的第三方转换网站。
| 核验项 | 操作 | 正常判断 |
|---|---|---|
| 配置是否导入 | 在 Stash 设置中进入配置文件,选择从 URL 下载;本地文件可通过 AirDrop,或从 iCloud、OneDrive 打开 | 配置出现在列表中,且没有 YAML 或字段解析错误 |
| 当前配置是否选中 | 在配置列表点选准备使用的文件 | 目标文件显示为当前配置,而不是只出现在历史列表 |
| 代理是否启动 | 返回首页点击启动,按系统提示完成网络权限或网络扩展授权 | Stash 显示运行状态,系统网络扩展处于连接状态 |
| 策略组是否有节点 | 进入代理或策略组页面,选择一个节点或自动策略组 | 策略组内有可选节点,且没有空组或不存在的引用 |
| 规则是否命中 | 打开连接记录或最近请求,访问一个已知测试域名 | 记录显示匹配到的规则和实际出站策略 |
| DNS、出口和流量是否符合预期 | 在连接详情或仪表盘查看请求、DNS相关信息、出口 IP 与流量统计;不同平台菜单名称以当前界面为准 | DNS 请求路径、出口 IP 和上下行流量与当前模式、策略组选择一致 |
iPhone 与 iPad 可按 iOS 文档中的“配置文件—从 URL 下载—选中—启动”完成首次导入。Stash Mac 是面向 macOS 的原生应用,提供 Dashboard、菜单栏操作和更多网络查看能力;macOS 端的具体入口以当前应用界面为准,可参考Stash Mac 官方说明。
Stash 配置、订阅、YAML 和 Override 怎么选
一句话判断:想快速启用就导入订阅,想长期自己维护就用本地 YAML,想保留托管订阅并增加个人规则就使用 .stoverride。主配置文件是必须的,Override 是可选的;官方说明中,Override 的优先级高于主配置。
| 对象 | 主要作用 | 适合场景 | 维护注意 |
|---|---|---|---|
| 远程订阅 | 从 URL 获取完整配置或节点集合 | 服务提供方已经给出可直接导入的配置 | 更新后可能改变原配置;订阅地址应按账号凭证保护 |
| 本地 YAML | 自行管理代理、策略组、DNS 和 rules | 需要从零编写或长期维护固定配置 | 必须检查缩进、字段名和各处引用关系 |
| Override | 只修改主配置中的部分字段 | 不想直接改托管订阅,或只需增加规则、策略组和 DNS | 文件后缀为 .stoverride,多个文件按启用顺序依次覆盖 |
| proxy-providers | 单独从 URL 更新代理节点集合 | 希望配置结构固定、节点可以独立更新 | 必须在策略组中通过 use 或其他支持方式引用 |
Override 的合并规则必须按官方文档处理:简单类型直接覆盖,字典递归合并,数组默认插入原数组前面;添加 #!replace 时完全替换,添加 #!append 时追加到数组末尾。多个 Override 按从上到下的顺序依次覆盖,相关细节见Stash 官方 Override 文档。
一个只修改 DNS 的 Override 示例可以写成下面这样,地址仅为占位内容,必须替换为你确认支持的 DNS 地址:
name: 自定义 DNS
desc: 仅覆盖 DNS 字段
dns:
nameserver: #!replace
- https://dns.example.com/dns-query不要把其他内核中的字段直接复制到 Stash。DNS 字段、数组合并方式和可用参数应以Stash 配置样例为准。
最小 YAML 示例:proxies、proxy-groups、rules 如何关联
下面是用于理解结构的示例,不包含真实节点信息,不能直接连接。带尖括号的内容必须替换为服务提供方给出的参数;节点端口以服务提供方资料为准,不是 Stash 设置页的默认值。
mode: rule
log-level: info
proxies:
- name: Proxy-1
type: ss
server: '<服务器地址>'
port: <端口>
cipher: '<加密方式>'
password: '<密码>'
proxy-groups:
- name: Auto
type: url-test
proxies:
- Proxy-1
interval: 300
- name: Proxy
type: select
proxies:
- Auto
- Proxy-1
- DIRECT
rules:
- DOMAIN-SUFFIX,local,DIRECT
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- GEOIP,CN,DIRECT
- MATCH,Proxy上例中的 Auto 已被 Proxy 策略组引用,MATCH,Proxy 又把未命中的连接交给 Proxy,因此它不是孤立策略组。官方策略组示例使用 type、proxies 和 interval 配置 url-test,没有必要自行添加未核实的测试地址,可参考Stash 官方策略组文档。
| 字段 | 作用 | 必须核对的关系 |
|---|---|---|
proxies | 定义具体代理节点 | 名称、协议类型和参数必须匹配服务提供方资料 |
proxy-groups | 把节点或其他策略组组合起来 | 策略组中的名称必须真实存在;策略组也可以引用另一个策略组 |
rules | 按顺序决定连接使用哪个出站 | 规则末尾的策略名称必须是节点、策略组或内置出站 |
MATCH,Proxy | 处理此前没有命中的连接 | 应放在 rules 最后作为兜底 |
Stash 规则按从上到下的顺序匹配,因此局域网和系统相关的直连规则应放在 GEOIP 之前,MATCH 兜底规则放最后。url-test 只放需要测试的节点或代理组,不要把 DIRECT 放进自动延迟测试组。
proxy-providers 节点为空:补齐 provider 与 use 引用
如果希望节点单独更新,可以使用远程代理集。官方文档要求在 proxy-providers 下定义远程资源,再在 proxy-groups 中通过 use 引用;规则不能直接引用远程代理集。
proxy-providers:
provider-a:
url: '<订阅地址>'
interval: 3600
proxy-groups:
- name: Auto
type: url-test
interval: 300
use:
- provider-a
- name: Proxy
type: select
proxies:
- Auto
- DIRECT
rules:
- MATCH,Proxy<订阅地址>必须替换为实际地址,且该地址应返回 Stash 能识别的代理集合内容。若策略组为空,按以下顺序检查:provider 的 URL 是否可访问;返回内容是否为空、登录页或错误页;需要鉴权时是否缺少服务端要求的请求头;use 中的名称是否与 provider-a 完全一致;策略组是否被 rules 或其他策略组实际引用。字段关系可核对Stash 官方远程代理集文档。
rule、global、direct 模式怎么选
mode 是流量处理的总开关,不是节点选择器。rule 按 rules 顺序分流,global 让连接统一使用当前代理,direct 让连接统一直连。Stash 配置样例对三种模式的定义可见官方配置样例。
| 模式 | 适用场景 | 排障用途 |
|---|---|---|
rule | 日常使用,需要按域名、IP 或其他条件分流 | 检查规则顺序、策略组和兜底出站 |
global | 临时让连接统一走当前代理 | 减少规则变量,验证节点与代理链路 |
direct | 临时让连接统一直连 | 判断本地网络、DNS 或目标服务是否本身可用 |
建议先用 rule 运行;目标打不开时临时切换到 global,确认当前节点和代理链路;再切换到 direct,比较本地网络与 DNS 结果。若全局模式仍无法连接,可参考站内的全局模式排障:如何快速退回可用网络。
按错误现象排查:不要先改一堆字段

| 错误现象 | 优先检查项 | 下一步操作 |
|---|---|---|
| 导入失败或配置不显示 | URL、文件内容和文件格式 | 确认返回的是配置内容而不是登录页、错误页或空内容,再检查 YAML 缩进 |
| YAML 解析错误 | 缩进、冒号、列表短横线和引号 | 先用 YAML 校验工具检查结构,再核对 Stash 字段;官方样例也建议用 YAML 校验工具检查格式 |
| 节点为空 | proxy-providers 返回内容和策略组引用 | 核对 provider URL、鉴权请求头、proxies 内容和 use 名称 |
| 策略组为空或没有生效 | 策略组名称、节点名称和引用链 | 确认策略组被 rules 或其他策略组引用,且没有拼写和大小写差异 |
| 配置能启动但目标打不开 | 规则顺序、当前模式和出站策略 | 查看连接记录命中规则,再按 rule、global、direct 进行对比 |
| 订阅更新后自己的修改消失 | 是否直接修改了托管订阅 | 把个人规则、策略组或 DNS 移到 .stoverride,并检查多个 Override 的启用顺序 |
- 先确认当前配置:导入成功不等于已经选中,先回到配置列表确认目标文件处于当前状态。
- 再检查 YAML:统一缩进,确认冒号后有空格,列表使用短横线,字符串中的特殊字符已正确处理。
- 检查引用:逐项对照
proxy-groups.proxies、proxy-groups.use和rules中的名称。 - 检查 Override:确认文件后缀为
.stoverride,并根据需要选择普通合并、#!replace或#!append。 - 最后看连接记录:核对命中规则、实际出站、DNS、出口 IP 和流量,而不是只看网页是否打开。
Stash 配置样例说明 YAML 缩进会影响整个结构,可先使用YAML 校验工具检查语法;字段是否支持仍要回到Stash 配置样例核对。若问题集中在 DNS 分流或解析路径,可继续参考站内的OpenWrt DNS 边界:解析、缓存与泄漏排查,但该页面的 OpenWrt 菜单和字段不应直接套用到 Stash。
常见问题
Stash 配置导入后没有节点怎么办?
先确认配置已经选中并成功启动,再检查订阅地址返回的是有效配置而不是登录页或错误页。如果使用 proxy-providers,还要核对 provider 的 url、请求头、返回内容和策略组中的 use 名称。
Stash 的订阅、本地 YAML 和 Override 怎么选?
想快速启用时导入订阅;需要长期维护固定结构时使用本地 YAML;不想直接修改托管订阅时使用 .stoverride。Override 适合保存个人规则、策略组和 DNS 等增量修改。
Stash 的 rule、global、direct 模式有什么区别?
rule 按 rules 顺序分流,适合作为日常模式;global 统一使用当前代理,适合验证节点;direct 统一直连,适合判断本地网络和 DNS 是否正常。排障时可依次对比三种模式。
Stash YAML 报解析错误,最先检查什么?
先检查缩进、冒号后的空格、列表短横线、引号和占位符,再确认字段是否出现在 Stash 官方配置样例中。语法通过后,再检查策略组和 rules 是否引用了不存在的名称。
Override 里的 DNS 应该怎么写?
先按 Stash 官方配置样例确认字段和层级,再修改 nameserver 或其他已核实字段。不要直接复制其他内核中的 enable、fallback 等字段,DNS 地址也必须替换为你确认支持的地址。
url-test 策略组必须填写测试 URL 吗?
Stash 官方策略组示例展示了 type、proxies 和 interval 等字段,没有必要自行添加未核实的测试地址。先按官方示例配置;如果当前版本界面或文档要求其他字段,应以对应版本文档为准。
macOS、iPhone 和 iPad 的 Stash 配置步骤一样吗?
核心流程相同,都是导入配置、选中当前文件并启动;macOS 使用原生 Stash Mac,提供 Dashboard、菜单栏操作和更多平台功能。具体菜单名称以当前平台界面为准。
相关阅读
参考资料
- 快速上手 – Stash 用户文档(stash.wiki)
- 配置样例 – Stash 用户文档(stash.wiki)
- 覆写文件(Override)– Stash 用户文档(stash.wiki)
- 策略组 – Stash 用户文档(stash.wiki)
- 远程代理集 – Stash 用户文档(stash.wiki)
- 规则类型 – Stash 用户文档(stash.wiki)
- Stash Mac – Stash 用户文档(stash.wiki)