背景：Clash Meta 为何更名为 mihomo？

如果你长期使用 Clash Meta 内核，一定注意到了 2023 年底至 2024 年初的一系列变化——原版 Clash 项目宣布归档停止维护，而由社区驱动的 Clash Meta 经历了一段高速迭代之后，在 2024 年正式以 mihomo 作为新的项目名称对外发布。这次更名不只是换了个名字，更意味着底层架构经历了深度重构：

  • 内核代码库迁移至独立仓库，与旧版 Clash 代码彻底解耦
  • YAML 配置格式在向后兼容基础上新增了大量字段
  • DNS 模块重写，支持 DoH3、QUIC 等新协议
  • 规则引擎引入 rule-set 外部规则集，性能大幅提升
  • TUN 模式（Mixed Port）稳定性显著增强，且支持 IPv6

对于仍在使用旧版 Clash.Meta（v1.x 时代）配置文件的用户来说，迁移到 mihomo 并非直接替换二进制文件那么简单——部分配置字段已被废弃或调整，直接替换可能导致代理失效或启动失败。本指南将系统梳理迁移过程中你需要检查和修改的每一处细节。

迁移前的准备工作

备份现有配置

在做任何改动之前，请先备份你的 config.yaml 文件以及任何自定义规则文件。mihomo 的配置文件默认存放在以下路径：

  • Windows：%USERPROFILE%\.config\mihomo\config.yaml
  • macOS / Linux：~/.config/mihomo/config.yaml
请务必在升级前将配置文件复制到安全位置。如果迁移出现问题，你可以随时还原旧配置并回退到原版内核。

确认当前内核版本

在终端中执行以下命令查看当前 Clash/Clash.Meta 的版本： 

# For old Clash / Clash.Meta binary
./clash -v

# For mihomo binary
./mihomo -v

如果输出中包含 mihomo 字样，说明你已经在使用新版内核，本指南的迁移部分可跳过，直接阅读新特性启用章节。

配置文件兼容性检查

mihomo 在大部分场景下向后兼容旧版 Clash.Meta 的 YAML 格式，但以下几类字段需要重点核查：

已废弃或调整的字段

旧字段 / 旧值 mihomo 等效写法 说明
clash-for-android 字段组 已移除 仅影响旧版 CFA 用户，mihomo 原生忽略
external-controller: 0.0.0.0:9090 保留兼容，建议改为 127.0.0.1:9090 监听所有接口存在安全风险
dns.enhanced-mode: redir-host dns.enhanced-mode: fake-ip 或 normal redir-host 模式已弃用
proxy-groups 中 type: fallback 继续支持，但建议改写为 type: url-test + lazy: true 行为略有差异，建议测试
直接在 rules 中写大量域名规则 迁移至 rule-providers 外部规则集 内联规则过多严重影响启动速度

TUN 配置段的变化

如果你原来使用了 TUN 模式，旧版写法与 mihomo 新版之间存在较明显的差异。旧版配置示例： 

# Old Clash.Meta TUN config
tun:
  enable: true
  stack: system
  dns-hijack:
    - 198.18.0.2:53
  auto-route: true
  auto-detect-interface: true

mihomo 新版推荐写法（启用更多特性）：

# mihomo recommended TUN config
tun:
  enable: true
  stack: mixed         # mixed mode offers best compatibility
  dns-hijack:
    - any:53           # intercept all DNS queries
  auto-route: true
  auto-detect-interface: true
  strict-route: true   # prevent traffic bypassing TUN
建议优先使用 stack: mixed——它结合了 system 栈的稳定性与 gvisor 栈的兼容性，是 mihomo 目前默认推荐的栈模式。

DNS 配置段的变化

mihomo 的 DNS 模块支持了更多上游类型，同时 nameserver-policy 字段的优先级逻辑也略有调整。核查要点如下：

  • 移除所有 enhanced-mode: redir-host 相关配置，改用 fake-ip
  • 如使用 fake-ip-filter，检查列表是否涵盖 NTP、游戏、P2P 等不适合 fake-ip 的域名
  • nameserver 建议至少保留一个国内 DNS（如 223.5.5.5）和一个 DoH（如 https://1.1.1.1/dns-query）
# Recommended DNS section for mihomo
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "+.lan"
    - "+.local"
    - "time.*.com"
    - "ntp.*.com"
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

mihomo 新特性启用指南

外部规则集 rule-providers

rule-providers 是 mihomo 最值得使用的新特性之一。它允许你从外部 URL 或本地文件加载规则列表，与旧版在 rules 字段内联几百条甚至几千条规则相比，性能提升非常显著——启动时间从数秒缩短到毫秒级，内存占用也大幅降低。 

# Define external rule providers
rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400
  cn-direct:
    type: http
    behavior: ipcidr
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/cncidr.txt"
    path: ./ruleset/cncidr.yaml
    interval: 86400

# Reference rule providers in rules section
rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,cn-direct,DIRECT
  - MATCH,Proxy

Sub-Rules 子规则组

mihomo 引入了 sub-rules 字段，支持将规则分组嵌套，避免主规则列表过长，同时实现更精细的分流逻辑。例如可以先按地区分组，再按应用类型细分，大幅提升规则可维护性。

GeoSite 与 GeoIP 数据库更新

mihomo 默认使用 GeoIP2 和 GeoSite 数据库，若你长期未更新这两个数据库，规则匹配精度可能下降。可在配置文件中指定自动更新： 

geodata-mode: true
geox-url:
  geoip: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
  geosite: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
  mmdb: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

常见迁移报错与解决方案

启动时报 cannot unmarshal 错误

这类错误通常是 YAML 字段类型不匹配或已废弃字段导致的。解决方法：

  1. 仔细阅读错误信息中 line X, column Y 指向的位置
  2. 对照本指南的废弃字段表，删除或替换对应字段
  3. 使用在线 YAML 校验工具排除语法错误

DNS 循环解析 / 全流量断网

开启 TUN 模式后，如果没有正确配置 dns-hijack 或 fake-ip-filter，可能出现 DNS 查询被代理本身拦截导致循环的问题。检查步骤：

  • 确认 dns.enable: true 已开启
  • 将 mihomo 的 External Controller 地址（如 127.0.0.1）加入直连列表
  • 在 fake-ip-filter 中添加 +.local 和 +.lan
如果问题依然存在，临时将 enhanced-mode 改为 normal 并重启，确认是否为 fake-ip 相关问题，再逐步排查。

TUN 模式提示权限不足

在 Linux / macOS 下，TUN 设备创建需要管理员权限。推荐做法：

  • macOS：使用支持 mihomo 内核的客户端（内置权限申请流程），无需手动 sudo
  • Linux：为 mihomo 二进制文件添加 cap_net_admin 能力： sudo setcap cap_net_admin=ep /usr/local/bin/mihomo
  • Windows：以管理员身份运行，或使用支持自动提权的 GUI 客户端

Rule Provider 拉取超时

首次启动 mihomo 时，rule-providers 需要从远程下载规则文件。如果网络环境较差，可能导致启动超时。解决方案：

  1. 在 rule-providers 中同时指定 path 本地路径，手动提前下载规则文件到对应位置
  2. 将规则 URL 替换为 jsDelivr CDN 加速版本（国内访问更快）
  3. 适当增大 timeout 值（默认 5 秒，可调至 30 秒）

迁移后验证

完成配置修改并重启 mihomo 后，建议通过以下步骤验证迁移是否成功：

  1. 访问 mihomo 的 Web UI（默认 http://127.0.0.1:9090/ui），确认内核版本显示为 mihomo
  2. 在「代理」页面检查所有节点是否正常加载
  3. 执行延迟测试（Latency Test），确认节点可正常连通
  4. 开启 TUN 模式，访问境外网站，确认流量走代理
  5. 访问国内网站（如百度），确认流量走直连，规则分流正常

如果以上步骤全部通过，恭喜你——迁移已完成！你现在运行的是当前最完善、最活跃维护的 Clash 系内核。

升级内核之后，客户端同样重要

许多用户在完成内核迁移后，依然使用多年前的老旧 GUI 客户端，这其实会导致你无法充分发挥 mihomo 的新特性。旧版客户端常见痛点包括：

  • 不支持 rule-providers 可视化管理，只能手动编辑 YAML
  • TUN 模式开关操作繁琐，甚至需要重启系统服务
  • 内核版本锁死，无法自动跟进 mihomo 的 bugfix 更新
  • UI 老旧，缺少节点延迟实时图表、流量统计等现代功能
  • 订阅管理粗糙，无法按节点组自动测速选优

如果你正在使用的客户端有以上问题，不妨考虑换用一款与 mihomo 深度集成的现代客户端。我们的 Clash 客户端专为 mihomo 内核设计，内置一键升级内核、可视化规则管理、TUN 模式图形化配置等功能，无需手动编辑 YAML 即可完成本指南中的所有操作。

免费下载 Clash 官方客户端 →，Windows、macOS、Android、iOS、Linux 全平台支持，10 分钟内即可完成从下载到上线的全流程。