---
title: "mihomo 配置编写指南"
type: practice
last_updated: 2026-08-07
tags:
  - "网络工具"
  - "mihomo"
  - "config.yaml"
  - "代理配置"
confidence: high
contested: false
raw_sources:
  - path: "raw/技术/mihomo/官方文档-配置编写-摘编.md"
    hash: "sha256:17ad7664cb257744a3277c1709d15912156a521dcac1f014ccfd335f3880b1cf"
  - path: "raw/技术/mihomo/官方文档-架构与核心概念-摘编.md"
    hash: "sha256:d2540a477284aa6b46e1ae6ba8d34b2f909c521a7ed32de9474203dd9301299a"
---

# mihomo 配置编写指南

## 页面定位

本页是**实践页**：给出从零编写 mihomo `config.yaml` 的逐步流程、最小可用模板与逐条检查清单，用于"帮用户写配置"这类任务。机制原理见 [[mihomo-内核与配置体系]]；字段级细节与全部节点写法见 `raw/技术/mihomo/` 摘编。

## 编写目标

产出一份可运行、分流正确、防污染、易维护的 mihomo 配置。适用场景：客户端（Windows/macOS/Linux 桌面）代理、路由器/网关透明代理、局域网共享代理。

## 编写流程（分步）

### 第 1 步：确定需求

- 使用形态：桌面客户端（用不用 TUN？）、局域网共享（allow-lan）、路由器（tproxy + iptables）。
- 节点来源：订阅（机场/自建订阅 URL）、手写节点（自建 ss/vless/trojan/hysteria2 等）。
- 分流诉求：代理境外（默认）、直连国内、广告拦截（reject 规则集）、特定域名/进程指定出口。

### 第 2 步：搭全局骨架

```yaml
mixed-port: 7890
allow-lan: false            # 局域网共享时 true，并考虑 authentication
mode: rule
log-level: info
ipv6: true
external-controller: 127.0.0.1:9090
secret: "替换为随机串"      # 绑 0.0.0.0 时必设
profile:
  store-selected: true
  store-fake-ip: true
```

### 第 3 步：配 DNS（fake-ip + 防污染）

按摘编第 6 节模板：`default-nameserver`（纯 IP）、`nameserver`（国内 DoH）、`fallback`（境外 TLS DoH）、`fallback-filter`（geoip CN）、`fake-ip-filter`（内网域名）。节点为域名时加 `proxy-server-nameserver`。

### 第 4 步：填节点（proxies）或订阅（proxy-providers）

- 有订阅：`proxy-providers` 一段即可（type http + url + interval + health-check + override.udp: true）。
- 手写节点：按类型填 `type/server/port` + 协议专属字段（ss 的 cipher/password、vmess 的 uuid/alterId、vless-reality 的 flow/servername/reality-opts、hysteria2 的 password/up/down 等），确认 `udp: true`（游戏等场景）。
- 节点域名解析：配 `proxy-server-nameserver`。

### 第 5 步：建代理组

- `select` 组「PROXY」（默认选中 url-test 组或具体节点）+ `url-test` 组「auto」（自动选优）+ 可选 fallback / load-balance 组。
- 健康检查 `url: "https://www.gstatic.com/generate_204"`、`interval: 300`、`expected-status: 204`。

### 第 6 步：写规则

自上而下：广告/隐私 reject → 代理规则集（RULE-SET,proxy,PROXY）→ 国内直连（GEOSITE,cn,DIRECT；GEOIP,CN,DIRECT,no-resolve）→ MATCH,PROXY 兜底。注意 `MATCH` 必须在最后。

### 第 7 步：可选增强

- TUN（桌面客户端）：`tun: {enable: true, stack: mixed, dns-hijack: ["0.0.0.0:53"], auto-route: true, auto-detect-interface: true}`；内网域名务必进 fake-ip-filter。
- 路由器透明代理：`tproxy-port` + `iptables.enable`；或 tun + auto-redirect。
- Web 面板：`external-ui` 指向 metacubexd 目录。

### 第 8 步：验证

```powershell
mihomo -t -f config.yaml     # 语法与结构校验
mihomo -d . -f config.yaml   # 实际启动（或 -d 指定 HomeDir）
# 启动后：面板/API 检查节点延迟、规则命中；curl -x http://127.0.0.1:7890 https://www.google.com 验证代理
```

## 检查清单（写完逐条过）

- [ ] YAML 缩进正确；含特殊字符的节点名/密码已加引号
- [ ] 每个节点 name 唯一；组引用名称与节点名一致
- [ ] `MATCH` 在规则最底部；GEOIP,CN,DIRECT 之前有代理规则集兜境外域名
- [ ] `fake-ip-filter` 覆盖 `*.lan`、`*.local` 及内网管理域名
- [ ] 节点为域名时已配 `proxy-server-nameserver`
- [ ] 需要 UDP 的场景节点 `udp: true`，组未 `disable-udp`
- [ ] allow-lan/API 对外时已配认证或 secret
- [ ] provider path 在 HomeDir 内（或已设 SAFE_PATHS）
- [ ] 无废弃字段（`sniffing`、组内 `interface-name`/`routing-mark`、全局 `client-fingerprint`）
- [ ] `mihomo -t` 通过；实际启动后分流验证通过

## 常见坑（高发错误）

1. 规则顺序错误 → 分流错乱（最常见）。
2. fake-ip 未过滤内网域名 → TUN 下访问不了 NAS/路由器。
3. 订阅节点域名解析污染 → 忘配 `proxy-server-nameserver`。
4. url-test/fallback 组不测 `use` 引入的节点 → 集合节点需在 provider 配 health-check。
5. rule-provider behavior 与文件格式不匹配 → 加载失败。
6. 对外暴露代理/API 无认证 → 被滥用。
7. 直接复制官方示例占位符 → 无法连接。

## 相关页面

- [[mihomo-内核与配置体系]] - 架构与核心机制
- [[Glossary|术语表]] - mihomo、fake-ip、代理组等术语
- [[Obsidian-CLI-Wiki-Maintenance]] - 本仓库 Wiki 维护实践

## 深入阅读

- raw 摘编：`raw/技术/mihomo/官方文档-配置编写-摘编.md`（字段级参考 + 模板）
- 官方文档：https://wiki.metacubex.one/ ；官方示例：https://github.com/MetaCubeX/mihomo/blob/Alpha/docs/config.yaml