TAG官网 - TAG VPN套餐价格 | Bronze、Silver、Gold计划 - TAG Pro网络加速返回首页

Mihomo 配置文件怎么切换?三种方法一次讲清

更新于 2026-11-03 · tagss11.buzz

简答:如果你要更换整份 YAML 配置,使用 mihomo -t -f 目标文件先校验,再用 mihomo -f 目标文件启动;如果只是更换节点,应在代理组中切换,而不是替换配置文件。桌面客户端通常需要导入并激活 Profile,运行中的 Mihomo 则可通过面板重载或重启。

定义:Mihomo 配置文件切换,是把当前运行实例使用的主配置 YAML 换成另一份配置;它不同于在同一份配置中切换代理节点,也不同于更新 proxy-providers 订阅文件。

先判断:你要切换的是整份配置,还是代理节点

很多人看到多个 YAML 文件时,第一反应是直接替换 config.yaml。但实际需求通常分为三类:更换整套端口、规则、DNS 和节点来源;只在现有配置的代理组里换一个节点;或者仅更新订阅提供者。三者的操作入口和风险不同。

你的目标正确做法是否需要重启内核
更换整套规则、端口、DNS 或节点来源切换主配置文件,或在客户端激活另一份 Profile通常需要重载或重启
只更换当前使用的节点在代理组中选择节点,或调用代理组 API通常不需要
更新订阅节点列表更新 proxy-providers 对应的 provider通常不需要更换主配置

Mihomo 官方 API 文档将“运行配置重载”和“代理组选择”列为不同接口:运行配置可通过 /configs 重载,代理组则通过 /proxies/{name}\ 选择节点。因此,先确认目标,再选择下面的路径。

方法一:命令行用 -f 切换整份 YAML 配置

适合直接运行 Mihomo、使用 systemd 或在服务器上管理多份配置的场景。建议先把配置放在同一工作目录中,例如:

mihomo-data/
├── mihomo
├── office.yaml
├── home.yaml
└── proxy_providers/
  1. 备份当前可用配置。复制当前 YAML,并用清晰名称区分用途,例如 office.yaml、home.yaml。不要直接覆盖唯一的可用文件。
  2. 先做语法校验。在 Mihomo 可执行文件所在目录运行:
    mihomo -t -f ./office.yaml
    Windows 可写成:
    mihomo.exe -t -f .\office.yaml
  3. 确认校验通过后启动。
    mihomo -f ./office.yaml
    如果你还需要指定工作目录,可结合 -d 使用,例如:
    mihomo -d ./mihomo-data -f ./office.yaml
  4. 观察启动日志。重点看配置解析、端口监听、DNS、TUN 和 provider 加载是否出现错误。不要只看到进程存在就认为配置已经生效。
  5. 复测代理端口。先确认新配置里的 mixed-port、port 或 socks-port,再在系统代理或客户端中使用对应端口。端口值不能凭旧配置猜测。

官方源码将 -f 定义为指定配置文件的启动参数;官方文档也说明 provider 的路径默认受 -d 指定的 HomeDir 限制,跨目录访问时还可能需要配置 SAFE_PATHS。启动参数说明与proxy-providers 路径说明可作为核对依据。

回滚方法:停止当前 Mihomo,再把启动命令中的 -f 改回上一份已验证的 YAML。若使用服务管理器,则修改服务的启动参数后重新加载服务配置;具体命令取决于你的服务管理方式,不建议直接套用其他系统的命令。

方法二:桌面客户端导入并激活 Profile

如果你使用的是带 Mihomo 内核的桌面客户端,通常不需要手动替换运行目录里的 config.yaml。通用流程是“导入配置—选中配置—激活—确认内核重载”。不同客户端的菜单可能叫“配置”“Profiles”“订阅”或“文件”,以下路径应按当前界面名称对应。

  1. 打开客户端的配置或 Profiles 页面。
  2. 选择“导入本地文件”或类似入口,选中目标 YAML;如果是订阅地址,则使用客户端提供的订阅导入入口,不要把订阅链接当成本地文件路径。
  3. 导入后先检查配置名称、端口、代理组和 provider 是否存在。
  4. 选中目标 Profile,点击“激活”“设为当前”或同义按钮。
  5. 等待内核重载或重启完成,再查看日志和当前配置页面。
  6. 开启系统代理前,先确认客户端显示的 HTTP、SOCKS 或 mixed 端口与当前配置一致。

如果客户端内置配置管理面板,激活配置后可能会先执行 mihomo -t 校验,再重启内核;这类行为取决于客户端封装方式,不能把某一个面板的按钮名称当成所有客户端的统一规则。MetaCubeX 的面板项目说明了“激活配置、校验、校验通过后重启内核”的流程,可用于理解这类客户端的工作方式:配置管理与激活说明。

如果导入后列表为空,优先检查文件是否真的是 Mihomo 可识别的 YAML、文件扩展名是否被系统隐藏、配置是否依赖相对路径,以及 provider 文件是否仍在原来的工作目录中。

方法三:运行中通过 API 重载配置或切换代理组

API 适合已经启用了 external-controller 的实例。它有两种用途:重载基本配置,或只切换代理组中的当前节点。

重载运行配置

官方 API 文档列出 /configs 的 GET 和 PUT 操作。可以先读取当前运行配置,确认端口和模式;修改文件后再执行重载。示例形式如下,实际地址和密钥必须替换为你自己的配置:

curl -H "Authorization: Bearer YOUR_SECRET" \
  -X PUT "http://127.0.0.1:9090/configs?force=true" \
  -d '{"path":"","payload":""}'

如果你只是想换节点,不要重载整份配置,而应先获取代理组名称,再向对应代理组发送选择请求:

curl -H "Authorization: Bearer YOUR_SECRET" \
  -X PUT "http://127.0.0.1:9090/proxies/代理组名称" \
  -d '{"name":"节点名称"}'

API 地址、路径、请求方法和返回状态应以当前 Mihomo 文档为准。官方说明还提醒,外部控制器如果监听在所有网卡上,应配合访问控制和密钥,避免把管理接口直接暴露给不受信任的网络:全局配置中的 External Control 说明。

什么时候需要重启而不是重载

如果只是更新可热加载的运行配置或切换代理组,重载通常足够;如果配置涉及客户端封装、TUN 权限、监听端口、工作目录或内核启动参数,重载失败时应按客户端提示完整重启。不要在没有确认端口和权限的情况下连续重启,否则容易把“配置错误”误判成“网络故障”。

proxy-providers、订阅文件和主配置是什么关系

proxy-providers 不是第二份主配置。它通常负责提供节点列表,主配置则负责端口、模式、DNS、规则和代理组等运行参数。主配置可以引用 provider,并通过代理组使用其中的节点。

官方文档将 provider 类型分为 http、file 和 inline,并说明 provider 可以有独立的 path。因此,直接编辑 provider 文件不等于修改主配置;如果 provider 来源是 HTTP 订阅,后续更新还可能重新写入该文件。provider 配置说明与provider 文件内容说明都应一起查看。

更稳妥的目录结构是把主配置和 provider 分开保存,例如:

mihomo-data/
├── office.yaml
├── home.yaml
└── proxy_providers/
    ├── office.yaml
    └── home.yaml

切换整份配置时,确认新 YAML 引用的 provider 路径仍然存在;切换订阅时,只更新对应 provider,不要为了换一个节点复制整份主配置。

切换后不生效:按现象排查并保留回滚路径

现象优先检查处理方式
客户端显示已切换,但端口不变是否只是切换了 Profile 名称,内核是否完成重载查看启动日志和运行配置,不要只看界面选中状态
节点列表为空provider 类型、URL、路径和代理组引用手动更新 provider,确认主配置中的引用名称一致
启动时报 YAML 或配置解析错误缩进、字段拼写、被引用的节点或代理组名称恢复上一份配置,再用 mihomo -t -f 单独校验新文件
端口被占用新配置的 mixed-port、port、socks-port关闭旧实例或修改端口,并同步更新系统代理设置
API 请求无响应external-controller 地址、端口、密钥和监听状态先读取 /version 或查看日志,再确认请求发往 API 端口而非代理端口
TUN 开启后无法联网新配置的 TUN、DNS、权限和系统路由先关闭 TUN 恢复普通代理,确认配置可用后再逐项启用

建议采用“新文件验证—停止旧实例—启动新文件—检查端口—检查日志—测试访问—保留旧文件”的顺序。任何一步失败,都回滚到上一份已验证配置,而不是继续叠加修改。

常见问题

Mihomo 可以直接把新文件改名为 config.yaml 吗?

可以,但不建议直接覆盖唯一的可用配置。更稳妥的做法是保留旧文件,先用 mihomo -t -f 新文件校验,再通过 -f 参数或客户端 Profile 激活新文件。

Mihomo 切换配置文件后,为什么节点还是原来的?

常见原因是只切换了主配置名称但没有重载内核,或者新旧配置引用了同一个 proxy-provider。先查看当前运行配置、启动日志和 provider 路径,再确认代理组是否引用了新 provider。

只想换节点,需要切换整份配置吗?

通常不需要。若节点已经在当前代理组中,直接在客户端选择节点即可;也可以通过 Mihomo API 的代理组接口切换。只有端口、规则、DNS 或节点来源整体改变时,才需要切换主配置。

mihomo -t -f 校验通过,就代表一定能联网吗?

不一定。该检查主要用于确认配置能被解析,不能替代实际连接测试。校验通过后,还要检查端口监听、provider 是否成功加载、代理组是否有可用节点,以及系统代理或 TUN 是否指向当前端口。

配置切换后端口变了,系统代理要怎么处理?

打开当前客户端或系统代理设置,核对 HTTP、SOCKS 或 mixed 端口是否与新配置一致。如果系统代理仍指向旧端口,界面可能显示内核运行正常,但浏览器仍然无法连接。

provider 文件会不会覆盖我的手动修改?

如果 provider 来源是 HTTP 订阅,更新时可能重新下载内容,因此不应把手动改动长期写在自动更新文件里。需要固定修改时,应调整主配置中的引用、过滤或 override 设置,并保留原 provider 作为回滚备份。

相关阅读

参考资料

  1. Mihomo 官方文档:API
  2. Mihomo 官方文档:全局配置与外部控制器
  3. Mihomo 官方文档:Proxy Providers
  4. Mihomo 官方文档:Provider 文件内容
  5. Mihomo 源码:启动参数 -f
  6. MetaCubeX Dashboard:配置激活与校验流程