Stash 配置 GitHub 怎么找、导入与排错：别下错同名软件
简答：找 Stash 配置 GitHub 文件时，先确认项目是网络客户端配置，而不是同名媒体软件；如果已经出现“配置导入成功却没有节点或连不上”，优先检查文件类型、远程代理来源和策略组引用。最快做法是打开具体 YAML 文件的 Raw 内容，核验未知远程地址、脚本和证书后，再导入 Stash。最近核验于 2026 年 10 月 24 日。
定义：Stash 配置文件是用 YAML 编写的网络客户端参数集合，用来定义运行模式、代理来源、策略组、规则、DNS 以及可选的远程资源；它本身不等于节点服务或订阅服务。
30 秒判断卡：这个 GitHub 文件能不能直接导入
先做下面四项检查，再决定是否下载。Stash 官方文档说明配置文件使用 YAML，配置文件与可选的 Override 覆写文件可以组合使用；GitHub 的 Raw 视图则用于查看或复制不带网页样式的原始文件。
| 检查项 | 看到什么才算基本合格 | 发现问题怎么办 |
|---|---|---|
| 项目类型 | README 明确写的是 Stash、Clash 格式或网络客户端配置 | 如果项目主题是媒体管理、照片或视频整理，不要当作网络配置导入 |
| 主配置字段 | 能看到 mode、proxy-groups、rules 或 dns 等字段 | 只有规则列表或节点列表时，先判断它是不是组件文件 |
| 远程来源 | 订阅、规则集和脚本地址来自你信任且有权使用的来源 | 未知地址、带个人权限的链接或无法解释的脚本不要直接启用 |
| 是否需要替换 | 模板明确提示用户填写自己的订阅或远程代理集 | 不要沿用作者预置的个人订阅地址 |
一句话判断：有主配置结构不代表一定能连接；配置只负责告诉客户端如何工作，仍需要合法、可信且有效的代理来源。本文只讨论网络客户端配置，不是同名媒体软件项目的使用说明。
Stash 官方配置样例还列出了 http、DNS、脚本和 MitM 等可选字段；因此“能解析”与“适合直接启用”是两件事，导入前仍要查看内容。参见Stash 配置样例。
GitHub 上常见的四类 Stash 配置文件
| 类型 | 主要内容 | 能否单独导入 | 重点核验 |
|---|---|---|---|
| 完整配置 | mode、proxy-groups、rules、dns 等 | 通常可以导入，但不保证能连接 | 代理来源、规则和远程资源是否可信 |
| 空白模板 | 已有字段和策略组，订阅地址可能是占位符 | 通常需要先替换来源 | proxy-providers 是否被策略组引用 |
| 规则集 | 域名、IP 或其他分流规则 | 不能当完整主配置 | 是否在 rule-providers 中声明，并在 rules 中调用 |
| 远程代理集 | 远程节点列表或 proxies 数据 | 不能替代主配置 | 是否被 proxy-groups.use 引用 |
Stash 文档将规则集定义在 rule-providers 下，再通过 rules 调用；远程代理集则需要在 proxy-providers 下定义，并由 proxy-groups 引用。把其中任意一个组件误当成完整配置，是“导入成功但没有节点或没有分流”的常见原因。参见Stash Rule Sets 文档和Stash Remote Proxy Set 文档。
从 GitHub 打开 Raw 并保存 YAML
- 先看仓库首页。阅读 README、适用客户端、许可证、依赖文件和最近提交，不要只根据项目名称或 Star 数量判断可用性。
- 进入具体配置文件。打开以
.yaml或.yml结尾的文件，确认它不是 README、网页导出内容或只有规则的组件。 - 点击 Raw。GitHub 官方文档给出的流程是进入仓库、打开目标文件，再点击右上角的
Raw；Raw 页面可以复制原始内容，也可以下载原始文件。参见GitHub 查看和理解文件。 - 手机端保存。在 Raw 页面使用系统分享菜单保存到“文件”，或复制原始文本后保存为 YAML。不要把 GitHub 网页源码、Markdown 预览或包含三反引号的代码块直接改名为 YAML。
- 只有需要多个文件时才下载 ZIP。GitHub 官方说明，Download ZIP 是某个分支、标签或提交的代码快照，不是单独配置文件；只导入一个 YAML 时，Raw 更直接。参见GitHub 下载代码归档。
如果 Raw 页面显示为空、下载后内容是 HTML、文件路径与 README 不一致，先回到仓库检查分支和文件位置，不要继续导入。
iPhone、iPad 与 macOS 的导入步骤
iPhone 或 iPad
- 准备远程订阅地址，或准备保存到 iCloud Drive、OneDrive 的本地 YAML 文件。
- 远程配置可在 Stash 的设置页面进入配置文件列表，选择从 URL 下载，粘贴地址并下载；具体菜单名称以当前版本界面为准。
- 本地文件可从“文件”应用、iCloud Drive、OneDrive 或 AirDrop 打开，并选择用 Stash 打开。
- 下载或打开后，在配置列表中选中要使用的文件，再回到首页启动。仅下载文件并不等于它已经成为当前生效配置。
- 首次启动先观察策略组、远程资源和日志，再测试目标应用，避免同时修改 DNS、规则和脚本。
macOS
- 将 Raw 下载的 YAML 保存到本地，或复制到 Mac 后确认文件内容仍是原始 YAML。
- 使用 Stash Mac 的打开方式导入该文件；如果系统界面与 iOS 不同，以当前版本的配置文件入口为准。
- 选中配置后启动，再从 Dashboard 或日志观察进程连接、策略组成员和远程资源状态。
- 如果 Mac 上已有其他网络代理、VPN 或系统网络工具，先暂时停用冲突项，再判断配置自身是否正常。
官方快速上手页面明确列出远程 URL、iCloud、OneDrive 和 AirDrop 等导入方式；Stash Mac 页面则说明 macOS 版本包含 iOS 版本的功能，并支持 Intel 与 Apple Silicon。页面显示快速上手文档最近更新于 2026 年 8 月 25 日，macOS 页面最近更新于 2026 年 10 月 14 日，实际菜单仍应以当前版本为准。参见Stash 快速上手和Stash Mac 文档。
订阅、策略组与 Override 应该怎样组合
更稳妥的做法是把“作者提供的主配置”和“你自己的修改”分开。Stash 官方说明主配置是必须的，Override 是可选的，且 Override 的优先级高于主配置；多个 Override 会按从上到下的顺序依次覆盖。因此，更新 GitHub 原文件时，尽量不要直接改动原始主配置，而是用单独的覆写文件放置自己的 DNS、策略组或规则调整。参见配置样例和Override 覆写文档。
下面是用于理解字段关系的最小示例。地址是占位符，不代表可用订阅；interval 的单位是秒，示例中的 3600 表示按文档字段格式设置的更新间隔。
proxy-providers:
my-provider:
url: https://example.com/your-config.yaml
path: ./providers/my-provider.yaml
interval: 3600
filter: "example"
proxy-groups:
- name: Auto
type: url-test
use:
- my-providerurl：远程代理集地址，必须是你有权使用且来源明确的地址。path：本地缓存路径，可用于保存远程代理集的缓存。interval：自动更新间隔，单位为秒。filter：按名称筛选远程代理集中的代理。header或headers：当服务端要求特定请求头或鉴权时按服务说明填写；不要把 Token 写进公开仓库。use：把提供商名称接入策略组；名称不一致时，策略组可能没有成员。
规则集的组合逻辑类似：在 rule-providers 中声明地址、行为、格式和更新间隔，再在 rules 中用 RULE-SET 引用。远程代理集与规则集都可以使用 path 做本地缓存，也可以按文档配置请求头。参见Remote Proxy Set和Rule Sets。
实践上可以按“主配置负责基础结构、代理提供商负责节点来源、策略组负责选择方式、规则集负责分流、Override 负责个人改动”的方式拆分。这样修改一个字段时，更容易定位是来源、策略组还是规则发生了变化。
配置导入成功但没有节点：按这个顺序排查
| 现象 | 先检查 | 处理方法 |
|---|---|---|
| 导入时报 YAML 错误 | 空格缩进、冒号、引号、列表短横线 | 确认没有 Tab、网页内容或 Markdown 三反引号，并用 YAML 校验工具检查结构 |
| 配置能选中但策略组为空 | proxy-providers 与 proxy-groups.use | 查看远程代理集是否下载成功，核对提供商名称是否完全一致 |
| 远程资源下载失败 | URL 返回内容、权限、请求头和有效期 | 确认返回的是配置或规则内容，而不是登录页、错误页或 HTML |
| 节点列表出现但全部失败 | 协议、地址、端口、认证信息 | 先测试同一策略组中的其他节点，不要立即判断整个配置失效 |
| 节点可用但应用打不开 | mode、rules、DNS 和应用自身设置 | 先用规则模式与直连模式做对照，再查看目标域名命中了哪条规则 |
| 某些功能要求证书或脚本 | MitM、CA、脚本提供商和远程地址 | 不认识的证书、脚本和远程地址先禁用或删除，并保留原文件备份 |
- 先确认 YAML 能否解析。
- 再确认
proxy-providers或rule-providers是否成功更新。 - 再确认策略组是否通过
use或规则引用获得成员。 - 然后检查 DNS 解析和应用规则。
- 最后才测试具体节点协议和网络连接。
每次只修改一项，并为原始配置保留副本。这样可以区分“文件结构错误”“远程来源失效”“策略组没有引用”和“节点本身不可用”，避免把所有问题都归咎于 GitHub 文件。
下载前的安全核验清单
- 看维护记录：检查 README、提交历史和文件变更，确认说明与当前字段是否一致。GitHub 的文件查看文档也提供了查看文件修订历史的方法。
- 看远程来源：重点查看配置中的远程代理集、规则集和脚本地址；无法解释用途的地址不要直接启用。
- 看证书与 MitM：出现 CA、证书密码或 MitM 配置时，先确认用途、来源和关闭方法，不要安装来源不明的证书。
- 看敏感信息：检查是否包含账号、密码、Token、带权限的订阅链接或个人 API 地址；不要把自己的凭据提交到公开仓库。
- 看许可证：确认文件能否修改、再发布或用于特定场景；没有说明时，不要把仓库内容称为官方模板。
- 留存原文件：导入前复制原始 YAML，后续用 Override 或本地副本记录个人修改。
如果国内站点正常、只有境外站点慢或丢包，才值得进一步检查跨境线路；若所有站点都异常，应先检查本地网络、DNS、系统时间、客户端冲突和路由器状态。不要因为 GitHub 配置导入失败，就直接把问题判断为线路故障。
常见问题
GitHub 上的 Stash 配置可以直接用吗？
不一定。它可能是完整配置、空白模板、规则集或远程代理集。即使文件能成功导入，也要确认代理来源有效、策略组有成员、远程资源下载正常，并检查是否包含无法解释的脚本、证书或请求地址。
为什么 Stash 配置导入成功，却显示没有节点？
优先检查远程代理集是否下载成功，以及策略组是否在 <code>use</code> 中引用了正确的提供商名称。还要确认订阅地址返回的是配置内容，而不是登录页、过期提示或 HTML 错误页面。
Stash 配置应该下载 Raw 还是 ZIP？
只需要一个 YAML 文件时，优先打开具体文件并点击 Raw；ZIP 是整个仓库的代码快照，适合需要多个配置、规则或脚本文件时使用。无论哪种方式，导入前都要确认内容不是网页源码。
Override 能不能代替主配置文件？
不能简单理解为替代。Stash 官方文档将主配置列为必须，Override 是可选的覆写文件，通常用于修改或叠加部分字段。建议保留主配置作为基础，再用 Override 放置个人 DNS、规则或策略组调整。
proxy-providers 和 rule-providers 有什么区别？
proxy-providers 用于提供远程代理集，通常由 proxy-groups 通过 use 引用；rule-providers 用于提供远程规则集，再由 rules 通过 RULE-SET 调用。前者影响可选择的代理，后者影响流量分流逻辑。
YAML 文件报错时最先检查什么？
先检查缩进是否统一使用空格、冒号后是否有空格、列表短横线是否完整、字符串引号是否成对，以及是否误复制了 Markdown 三反引号。建议一次只改一个字段，并用 YAML 校验工具确认结构。
配置里的 MitM、证书和脚本是否应该开启？
不建议看到后直接开启。MitM 和证书会改变 HTTPS 请求处理方式，脚本也可能读取或修改请求内容。只有在明确知道来源、用途、权限范围和关闭方法时才考虑使用，否则应先禁用并保留原始配置。
Stash 配置文件和订阅服务有什么区别？
配置文件定义客户端的模式、DNS、规则、策略组和远程资源；订阅服务提供代理节点或代理列表。配置文件不会自动生成节点，没有合法、可信且仍有效的代理来源时，配置正确也可能无法连接。