Mihomo 订阅配置教程：从格式识别到连接验证的完整步骤
简答：Mihomo 订阅配置的最快路径是：先确认服务端提供的是 Clash/Mihomo 格式，再导入远程配置或 proxy-providers，激活当前配置，选择代理组并开启系统代理。导入后没有节点时，优先检查返回内容、HTTP 状态码、格式和代理组引用，不要先修改 DNS、MTU 或 TUN。
定义：Mihomo 订阅配置，是把远程配置文件或节点提供器地址交给 Mihomo，使核心获取节点集合，并通过代理组、规则模式和系统代理使用这些节点。
先看速查卡：你拿到的订阅属于哪一种
本文围绕 Mihomo 核心展开，图形客户端的菜单可能显示为“配置”“Profiles”“远程配置”或“订阅管理”，具体名称以实际界面为准。Mihomo 的官方配置文档将远程节点集合定义为 proxy-providers，它与能够直接被激活的完整配置不是同一层级。
| 拿到的内容 | 通常是什么 | 能否直接按完整配置导入 | 成功标志 |
|---|---|---|---|
| HTTP 或 HTTPS 订阅地址 | 可能是完整配置，也可能是节点集合 | 需看服务端返回内容和客户端入口 | 出现配置文件、节点和可用代理组 |
| Clash、Clash Meta 或 Mihomo YAML | 完整配置或 Provider 文件 | 完整配置通常可直接使用，Provider 需被代理组引用 | YAML 能通过校验，代理组出现节点 |
| sing-box、V2Ray 或单节点 URI | 其他格式配置或单个节点 | 不能默认当作 Mihomo YAML | 需由提供方给出兼容格式或转换说明 |
| Base64、JSON 或网页 HTML | 编码内容、接口返回或错误页面 | 不能直接按 YAML 使用 | 先确认真实响应内容和格式 |
先试这一步：把订阅地址复制到浏览器或命令行，只检查响应状态和内容类型，不要在公开平台粘贴完整链接。若返回的是登录页、错误页、JSON 错误信息或空内容，先处理链接、权限或服务端问题。
官方文档显示，proxy-providers 支持 http、file 和 inline 类型；HTTP 类型需要配置 url，Provider 还可以通过 use 被代理组引用。可查看 Mihomo 官方 proxy-providers 配置文档 与 Mihomo 官方代理组配置文档。
开始前准备：链接、格式、备份和核心版本
- 准备订阅链接：从服务提供方后台复制完整地址，不要手动删掉路径、参数或 token。真实订阅链接应按凭据处理，不能公开发到群聊、截图、代码仓库或工单。
- 选择格式：优先选择明确标注为 Clash、Clash Meta 或 Mihomo 的格式。sing-box、V2Ray 和单节点 URI 不要直接改后缀当作 YAML。
- 确认运行方式：图形客户端通常由界面管理配置；命令行方式则需要找到 Mihomo 核心和当前
config.yaml的目录。 - 先备份：复制当前配置为
config.yaml.bak，并保留上一份能够启动的 Provider 缓存或配置文件。 - 版本需核实：本文不写死 Mihomo 或图形客户端版本号。核心版本、字段和菜单会变化，应以 Mihomo 发布页及客户端实际内置核心为准。
如果订阅服务要求额外的请求头、过滤参数、转换参数或特殊格式，最小配置不一定能够直接适配。应以订阅提供方说明和实际返回内容为准，不能因为 URL 能下载就断定节点一定可用。
图形客户端导入：下载、激活、选择和验证
不同平台和图形客户端的入口名称可能不同，但可以按“添加地址—下载—激活—选择代理组—开启代理—验证”的顺序操作。
- 打开客户端的配置、Profiles、远程配置或订阅管理页面。
- 添加订阅 URL，名称可写成
work-subscription。名称不要包含 token、UUID 或密码。 - 点击下载、保存或更新。成功标志不只是出现“已保存”，还应能看到更新时间、配置大小或配置内容变化。
- 选中刚下载的配置，执行激活、设为当前配置或类似操作。下载配置不等于核心已经使用它。
- 进入代理组页面，选择一个具体节点或自动选择组。若代理组为空，先回到格式和 Provider 引用检查。
- 先开启系统代理，再用普通网页和目标应用测试。只有系统代理确认正常后，才进入 TUN 测试。
如果客户端提供配置编辑器或控制面板，可先执行配置校验，再重载核心。MetaCubeX 的 Dashboard 项目说明了激活配置、使用 mihomo -t 校验，并在校验通过后重启核心的流程；这属于 Dashboard 项目说明，不等于所有图形客户端的菜单都完全相同。可查看 MetaCubeX Dashboard 项目说明。
Windows、macOS、Android、iOS、Linux 操作差异清单
下面只列出平台层面的操作重点，不把某个第三方图形客户端的菜单名称当作所有 Mihomo 客户端的统一界面。
| 平台 | 导入时重点 | 首次验证顺序 | 常见分流点 |
|---|---|---|---|
| Windows | 在配置或 Profiles 页面添加 URL；确认当前配置已激活 | 检查混合端口监听，再开启系统代理 | 端口被其他代理程序占用；TUN 或防火墙授权未完成 |
| macOS | 添加远程配置后确认配置文件已切换为当前项 | 先测试系统代理，再测试需要更强接管能力的应用 | 系统代理开关状态；TUN 网卡和防火墙设置 |
| Android | 导入后确认应用获得 VPN 权限，并选择当前配置 | 开启 VPN 后测试一个浏览器页面和一个应用 | 系统 VPN 冲突；Private DNS 可能影响 DNS 接管 |
| iOS | 按客户端提供的订阅或配置入口导入，不要假设桌面端菜单相同 | 确认 VPN 配置授权、当前节点和连接状态 | 系统 VPN 权限、后台状态和应用自身代理设置 |
| Linux | 命令行运行时确认工作目录、配置文件路径和文件权限 | 先执行校验命令，再启动核心和测试端口 | 防火墙、路由、TUN 权限和 Provider 文件路径 |
表格中的平台差异是操作排查清单，不代表所有客户端都支持相同功能。尤其是 TUN、VPN 权限和系统代理能力，必须以当前客户端实际提供的功能为准。
命令行最小配置：使用 proxy-providers 获取节点
下面是一份按官方字段组织的最小结构。它不是填入占位地址后即可使用的成品：必须把 url 替换为真实的 Mihomo/Clash 格式地址，并确认服务端返回内容符合 Provider 要求。
mixed-port: 7890
mode: rule
log-level: info
proxies: []
proxy-providers:
my-subscription:
type: http
url: https://example.com/replace-with-your-subscription
path: ./proxy_providers/my-subscription.yaml
interval: 3600
proxy-groups:
- name: PROXY
type: select
use:
- my-subscription
rules:
- MATCH,PROXY
这份配置的关系是：proxy-providers 下载节点集合；proxy-groups.use 将 Provider 引入代理组；rules 把未被其他规则匹配的流量交给 PROXY。官方文档明确区分了 Provider 的 url、本地 path、更新间隔和代理组的 use 引用。
- 把
url替换为真实订阅地址。 - 确认
path位于 Mihomo 工作目录或允许的安全路径内。 - 确认 Provider 返回的是 Mihomo/Clash 可识别的节点内容，而不是 HTML 错误页、JSON 报错或其他客户端格式。
- 在配置文件所在环境执行
mihomo -t -f config.yaml。 - 校验通过后再启动或重载核心；校验失败时优先修复输出中的第一条错误。
如果使用图形客户端或 Dashboard，不能随意删除控制接口字段。只有纯命令行且不需要控制面板时，才可以不配置外部控制器；需要 Dashboard 或 GUI 连接时，应按客户端要求保留控制接口，并将监听地址限制在本机，设置访问密钥。
导入后没有节点、更新失败：按可复现证据分流
| 现象 | 先检查什么 | 下一步怎么做 |
|---|---|---|
| 下载成功但节点为空 | 响应内容、格式、Provider 是否被代理组引用 | 确认不是 HTML、JSON 错误或空内容；检查代理组是否写了 use: my-subscription |
| 更新返回 401、403 或 404 | 订阅权限、有效期、路径和 token | 重新从服务端复制链接；不要通过改后缀或手动拼接参数解决 |
| 更新超时或 TLS 证书错误 | 当前网络、域名解析、证书时间和重定向 | 记录错误原文，单独测试订阅 URL；不要先改 DNS 或关闭证书校验 |
| YAML 解析失败 | 缩进、重复字段、特殊字符和引号 | 执行 mihomo -t -f config.yaml，按第一条错误逐项修复 |
| 有节点但代理组为空 | Provider 名称和 use 引用是否完全一致 | 检查大小写、缩进和代理组名称；不要只看 Provider 文件是否下载 |
| 系统代理开启但浏览器不通 | 混合端口是否监听、节点是否选中、其他代理是否冲突 | 确认客户端端口与 mixed-port 一致，只保留一个代理程序测试 |
| 部分应用不跟随代理 | 应用是否遵循系统代理 | 先确认系统代理链路正常，再单独测试 TUN 或应用自身代理设置 |
如果启用了控制接口，可以用 API 查看当前配置、Provider、日志和连接信息。官方 API 文档列出了 /configs、/providers/proxies、/logs、/connections 和 /version 等接口；控制接口的 secret 属于凭据，不要公开。可查看 Mihomo 官方 API 文档。
连接验证：节点、出口、IPv6 和 DNS 分开看
- 验证节点：代理组中应能看到 Provider 生成的节点，并且当前选择项不是直连。
- 验证端口：确认客户端显示的 HTTP、SOCKS 或 mixed 端口与实际配置一致，避免端口冲突导致“核心运行但应用不通”。
- 验证出口 IPv4：开启代理后，在一个你信任的 IP 查询页面查看出口地址；再关闭代理重复测试。结果只代表当前设备、当前网络和当前节点的即时状态。
- 验证 IPv6：如果系统和网络同时启用 IPv6，分别检查 IPv4 与 IPv6 出口。若 IPv6 直连而 IPv4 走代理，先暂停 IPv6 或按当前客户端文档配置，再继续测试。Mihomo 的全局配置和节点配置都包含 IPv6 相关选项，不能只看 IPv4 结果。
- 验证 DNS 路径：检查 Mihomo DNS 是否启用、是否使用 TUN 的 DNS 接管，以及日志中是否出现解析错误。DNS 结果只能说明当前测试路径，不构成绝对的隐私或安全保证。
- 验证连接链：通过控制接口的连接信息或日志确认目标连接的规则、代理链和错误类型。官方 API 可返回连接的目标地址、协议、规则和代理链信息。
Mihomo 官方 DNS 文档说明，代理节点域名可以使用 proxy-server-nameserver 单独解析；如果 DNS 配置要求通过代理访问上游，还要避免“解析代理节点本身”时形成循环依赖。遇到解析失败时，应先查看配置和日志，再决定是否调整 DNS。可参考 Mihomo 官方 DNS 配置文档。
规则模式、全局模式与 TUN：正确的启用顺序
| 模式 | 作用 | 适合什么时候用 |
|---|---|---|
| 规则模式 | 根据规则决定直连或代理 | 日常使用和首次完成基础验证 |
| 全局模式 | 把流量交给选定的代理策略 | 排查是否是规则误判；测试后可切回规则模式 |
| 直连模式 | 所有流量直接连接 | 确认本地网络、浏览器和 DNS 是否本身正常 |
官方全局配置文档列出了 rule、global 和 direct 三种运行模式，默认模式为规则模式。可查看 Mihomo 官方全局配置文档。
TUN 不要作为第一步。它适合接管不遵循系统代理的应用，但会改变路由、DNS 或虚拟网卡行为，部分平台还需要权限、防火墙或 VPN 授权。建议按以下顺序操作：
- 先在规则模式下确认节点和系统代理正常。
- 备份当前配置，并关闭其他代理软件。
- 单独启用 TUN，只测试一个应用和一个目标地址。
- 如果出现断网、循环连接或 DNS 异常，立即关闭 TUN 并恢复备份。
- 不要在同一次排查中同时修改 TUN、DNS、MTU、IPv6 和规则。
Mihomo TUN 文档列出了 auto-route、auto-redirect、strict-route、dns-mode 和 dns-hijack 等字段，并明确说明不同系统的行为存在差异。需要核对时，应以当前版本文档和客户端界面为准，不能直接复制其他设备的完整 TUN 配置。可查看 Mihomo 官方 TUN 配置文档。
回滚与安全清单
- 保留上一份能够启动的
config.yaml，更新订阅前先复制备份。 - 订阅 URL、token、UUID、密码和控制接口 secret 都按凭据保护。
- 不要把真实订阅地址放进公开仓库、截图、文章示例或工单。
- 更新失败时先恢复旧配置，不要立刻删除所有 Provider 缓存。
- 控制接口只在确有需要时开启，并尽量绑定本机地址；需要远程访问时应设置访问密钥并限制来源。
- 若错误信息涉及未知字段、版本不兼容或菜单缺失，标记为“需核实”，以当前核心和客户端实际界面为准。
本文是本项目的第三方使用指南，不是 Mihomo 或任何订阅服务的官方页面。订阅是否有效、何时到期、支持哪些格式，应以订阅提供方当前说明为准。
相关页面：完成导入后继续定位连接问题
如果你已经完成 Mihomo 订阅导入，可以按问题表现继续阅读：
- Mihomo 订阅配置怎么导入：适合只需要按界面完成导入和连接验证的读者。
- DNS 设置与连接排查：适合日志明确出现解析失败、域名打不开或 DNS 超时的情况。
- 代理速度慢排查：用于区分节点、DNS、客户端和本地网络因素。
- 连接问题排查：适合已经确认配置激活，但仍无法建立连接的情况。
常见问题
Mihomo 订阅链接应该选什么格式？
优先选择服务提供方明确标注为 Clash、Clash Meta 或 Mihomo 的格式。sing-box、V2Ray 和单节点 URI 不能默认当作 Mihomo YAML 使用；具体转换方式应以提供方说明为准。
为什么订阅导入成功，但 Mihomo 里没有节点？
先确认当前配置已经激活，再检查 HTTP 状态码、返回内容是否为空、内容是否为 HTML 或 JSON 错误，以及 Provider 是否通过代理组的 <code>use</code> 字段被引用。下载记录存在不代表节点已经生效。
Mihomo 配置检查命令是什么？
命令行环境可以运行 <code>mihomo -t -f config.yaml</code>。校验通过后再启动或重载核心；失败时优先处理输出中的第一条错误。若图形客户端没有终端入口，应使用客户端提供的配置校验功能。
Windows、macOS、Android、iOS 和 Linux 的导入方法一样吗？
核心逻辑相同，都是添加订阅、激活配置、选择代理组并验证连接，但菜单名称、VPN 权限、TUN 支持、防火墙和文件路径存在差异。应按平台清单操作，并以当前客户端实际界面为准。
订阅更新返回 401、403 或 404 怎么办？
这些状态通常需要先核对订阅权限、有效期、路径和 token。重新从服务端复制完整链接，确认当前网络能够访问该地址；不要通过改后缀或手动拼接参数来替代有效订阅。
应该先开系统代理还是 TUN？
先开启系统代理，完成节点、代理组、端口和普通网页验证后，再单独测试 TUN。TUN 会影响路由和 DNS，排查时不要与其他代理软件同时开启。
如何判断 IPv6 或 DNS 是否绕过了当前代理？
分别检查代理开启和关闭时的 IPv4、IPv6 出口，并查看 Mihomo 日志、连接信息和 DNS 配置。结果只代表当前设备、网络和节点的即时状态，不构成绝对的隐私或安全保证。
为什么最小 proxy-providers 配置不一定适用于所有订阅？
不同服务端返回的数据格式、请求头、过滤参数和节点字段可能不同。最小配置只展示 Mihomo 官方字段之间的关系，能否直接使用必须以实际返回内容和订阅提供方说明为准。