Mihomo2Singbox

一个高性能的 Mihomo (ClashMeta) 配置转换工具，可以将 Mihomo 配置文件精确转换为 Sing-box 格式，完全兼容 sing-box 1.12.0+ 的最新格式要求。

⚠️ 重要提示

目前仅完整测试了 Shadowsocks 节点转换

其他协议 (VMess, VLESS, Trojan, Hysteria2, TUIC) 的代码已实现，但尚未进行完整测试。

如果您需要使用其他协议，请先在测试环境中验证转换结果。

🎉 最新更新 v0.1.0:

✅ 修复了 --tun-simple 参数无法独立启用 TUN 功能的关键 bug

✅ 现在支持标准 Python 包安装和分发

✅ 完全兼容 uv 现代 Python 包管理器

✅ 经过完整测试的 Shadowsocks 节点转换

✨ 核心特性

⚠️ 重要提示: 目前仅完整测试了 Shadowsocks 节点转换，其他协议代码已实现但未完整测试

🚀 Shadowsocks 完整支持 - 经过完整测试，支持各种插件和配置
🔧 现代化格式 - 完全支持 sing-box 1.12.0+ 新格式，通过官方验证
🌐 智能 DNS 转换 - 自动升级到新的 DNS 服务器格式
📋 规则集优化 - 自动生成远程 rule-sets 替代内置规则，性能更佳
🔌 插件兼容 - 正确处理 obfs-local, v2ray-plugin 等插件
🛡️ TUN 支持 - 支持高级和简单 TUN 配置模式
⚡ 高性能 - 使用 uv 进行依赖管理，启动速度提升 10-100x
📦 标准包 - 支持 pip/uv 安装，可作为 Python 模块使用
✅ 配置验证 - 生成的配置通过 sing-box check 验证

📦 安装方式

方式 1: 使用 uv (推荐)

uv 是一个现代化的 Python 包管理器，速度快，依赖解析准确。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法 A: 直接运行 (推荐)
uv run --from mihomo2singbox mihomo2singbox input.yaml -o output.json

# 方法 B: 克隆项目使用
git clone https://github.com/n-WN/mihomo2singbox.git
cd mihomo2singbox
uv run mihomo2singbox input.yaml -o output.json

方式 2: 使用 pip

# 方法 A: 从 PyPI 安装 (TODO: 待发布)
pip install mihomo2singbox

# 方法 B: 从源码安装
git clone https://github.com/n-WN/mihomo2singbox.git
cd mihomo2singbox
pip install -e .

# 运行
mihomo2singbox input.yaml -o output.json

方式 3: 开发环境

# 克隆项目
git clone https://github.com/n-WN/mihomo2singbox.git
cd mihomo2singbox

# 使用 uv 管理环境
uv sync

# 运行测试
uv run mihomo2singbox --help

🚀 快速开始

基本用法

# 基本转换
uv run mihomo2singbox input.yaml

# 指定输出文件
uv run mihomo2singbox input.yaml -o output.json

# 自定义监听地址和端口
uv run mihomo2singbox input.yaml --listen 0.0.0.0 --port 7891

# 启用 TUN 模式 (高级配置)
uv run mihomo2singbox input.yaml --tun

# 启用 TUN 模式 (简单配置，兼容性更好)
uv run mihomo2singbox input.yaml --tun-simple

# 禁用 rule-sets，使用传统 GeoIP/Geosite
uv run mihomo2singbox input.yaml --disable-rule-sets

# 调整日志级别
uv run mihomo2singbox input.yaml --log-level debug

配置验证和运行

# 转换配置
uv run mihomo2singbox input.yaml -o singbox_config.json

# 验证生成的配置
sing-box check -c singbox_config.json

# 使用配置运行 sing-box
sing-box run -c singbox_config.json

命令行选项

uv run mihomo2singbox --help

查看完整的命令行参数说明：

参数	说明	默认值
`input`	输入的 Mihomo 配置文件路径	必需
`-o, --output`	输出的 Sing-box 配置文件路径	`singbox_config.json`
`--listen, -l`	入站监听地址	`127.0.0.1`
`--port, -p`	入站监听端口	`7890`
`--tun, -t`	启用 TUN 入站 (高级配置)	`False`
`--tun-simple`	使用简单 TUN 配置 (兼容模式)	`False`
`--disable-rule-sets`	禁用 rule-sets，使用传统规则	`False`
`--log-level`	日志级别	`info`
`--clash-api-port`	Clash API 端口	`9090`

🔧 TUN 功能说明

TUN 模式对比

模式	参数	特点	适用场景
高级 TUN	`--tun`	完整配置，IPv6 支持，高级路由	Linux/Android 系统，需要完整功能
简单 TUN	`--tun-simple`	基础配置，兼容性好	旧版系统，兼容模式
混合模式	`--tun --tun-simple`	使用简单配置	明确要求简单模式时

TUN 配置示例

# 高级 TUN 配置 (推荐)
uv run mihomo2singbox input.yaml --tun -o advanced_tun.json

# 简单 TUN 配置 (兼容模式)
uv run mihomo2singbox input.yaml --tun-simple -o simple_tun.json

高级 TUN 配置特点:

IPv4 + IPv6 双栈支持
自动路由和重定向
高级 MTU 和超时设置
完整的路由表配置

简单 TUN 配置特点:

仅 IPv4 支持
基础自动路由
更好的兼容性
更少的系统要求

📋 协议和功能支持

⚠️ 测试状态说明: 目前仅 Shadowsocks 协议经过完整测试，其他协议代码已实现但测试有限

支持的代理协议

协议	支持状态	测试状态	特性	插件支持
Shadowsocks	✅ 完整支持	✅ 完整测试	所有加密方式	obfs-local, v2ray-plugin
VMess	✅ 代码实现	⚠️ 有限测试	WebSocket, gRPC 传输	-
VLESS	✅ 代码实现	⚠️ 有限测试	标准配置	-
Trojan	✅ 代码实现	⚠️ 有限测试	TLS 配置	-
Hysteria2	✅ 代码实现	⚠️ 有限测试	带宽控制，UDP 转发	-
TUIC	✅ 代码实现	⚠️ 有限测试	QUIC 传输	-

转换功能支持

功能	支持状态	说明
代理组	✅ 完整支持	select, url-test, fallback, load-balance
路由规则	✅ 完整支持	域名、IP、端口、进程等规则
DNS 配置	✅ 完整支持	智能升级到 v1.12.0+ 格式
Rule Sets	✅ 完整支持	自动转换 GeoIP/GeoSite 为远程规则集
TUN 模式	✅ 完整支持	高级和简单两种配置模式
Clash API	✅ 完整支持	保持兼容的 API 配置

🔧 配置转换示例

输入配置 (Mihomo YAML)

proxies:
  - name: "示例节点"
    type: ss
    server: example.com
    port: 443
    cipher: aes-256-gcm
    password: password123
    plugin: obfs
    plugin-opts:
      mode: http
      host: www.bing.com

proxy-groups:
  - name: "Proxies"
    type: select
    proxies: ["示例节点", "DIRECT"]

rules:
  - DOMAIN-SUFFIX,google.com,Proxies
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Proxies

dns:
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

输出配置 (Sing-box JSON)

{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "dns": {
    "servers": [
      {
        "tag": "local",
        "address": "local",
        "detour": "direct"
      },
      {
        "tag": "dns_0",
        "address": "223.5.5.5",
        "detour": "direct"
      },
      {
        "tag": "dns_1",
        "address": "1.1.1.1",
        "detour": "direct"
      }
    ],
    "final": "dns_0"
  },
  "outbounds": [
    {
      "tag": "示例节点",
      "type": "shadowsocks",
      "server": "example.com",
      "server_port": 443,
      "method": "aes-256-gcm",
      "password": "password123",
      "plugin": "obfs-local",
      "plugin_opts": "obfs=http;obfs-host=www.bing.com",
      "network": "udp"
    },
    {
      "tag": "Proxies",
      "type": "selector",
      "outbounds": ["示例节点", "direct"]
    },
    {
      "tag": "direct",
      "type": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "domain_suffix": ["google.com"],
        "outbound": "Proxies"
      },
      {
        "domain_suffix": ["baidu.com"],
        "outbound": "direct"
      },
      {
        "rule_set": "geoip-cn",
        "outbound": "direct"
      }
    ],
    "rule_set": [
      {
        "tag": "geoip-cn",
        "type": "remote",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
        "download_detour": "direct"
      }
    ]
  }
}

🎯 版本更新说明 (v0.1.0)

✅ 重要修复

TUN 逻辑修复 - 修复了 --tun-simple 参数无法独立启用 TUN 功能的关键 bug
包结构优化 - 重构为标准 Python 包，支持 pip/uv 安装
类型注解现代化 - 升级到 Python 3.11+ 现代类型注解语法
依赖管理优化 - 完全兼容 uv 包管理器，启动速度大幅提升

✅ Sing-box 1.12.0+ 兼容性

DNS 配置现代化 - 使用新的 servers 数组格式
插件选项修复 - 正确输出字符串格式的 plugin_opts
路由规则升级 - 使用 action 格式替代遗留特殊出站
Rule-sets 支持 - 自动生成远程规则集，性能更佳

🔧 技术亮点

# TUN 逻辑修复示例
enable_tun = args.tun or args.tun_simple  # 现在两个参数都能启用 TUN

# 插件选项智能转换
def _convert_plugin_opts_to_string(self, plugin: str, opts: Dict) -> str:
    if plugin == "obfs":
        result = []
        if "mode" in opts:
            result.append(f"obfs={opts['mode']}")
        if "host" in opts:
            result.append(f"obfs-host={opts['host']}")
        return ";".join(result)

📊 性能数据

基于真实测试配置的转换性能：

配置规模: 26,924 行 JSON 输出
代理节点: 1,463 个 Shadowsocks 节点
代理组: 21 个选择器组
路由规则: 25,387 个规则
转换时间: < 5 秒
验证状态: ✅ 通过 sing-box check

🛠️ 高级功能

批量转换

# 转换目录中所有 YAML 文件
for file in *.yaml; do
    echo "转换 $file..."
    uv run mihomo2singbox "$file" -o "${file%.yaml}.json"
done

# 使用 find 命令批量处理
find . -name "*.yaml" -exec uv run mihomo2singbox {} -o {}.json \;

自动化脚本

#!/bin/bash
# convert_and_run.sh - 转换并运行 sing-box

INPUT_FILE="$1"
OUTPUT_FILE="singbox_config.json"

# 转换配置
echo "转换配置文件..."
uv run mihomo2singbox "$INPUT_FILE" -o "$OUTPUT_FILE"

# 验证配置
echo "验证配置文件..."
if sing-box check -c "$OUTPUT_FILE"; then
    echo "配置验证成功，启动 sing-box..."
    sing-box run -c "$OUTPUT_FILE"
else
    echo "配置验证失败！"
    exit 1
fi

配置文件验证

# 转换并自动验证
uv run mihomo2singbox input.yaml -o output.json && sing-box check -c output.json

# 查看配置文件特定部分
jq '.outbounds[0]' output.json          # 第一个出站
jq '.dns.servers' output.json           # DNS 服务器配置  
jq '.route.rules | length' output.json  # 路由规则数量
jq '.inbounds[] | select(.type == "tun")' output.json  # TUN 配置

性能优化建议

# 对于大型配置文件，启用 rule-sets 优化 (默认启用)
uv run mihomo2singbox large_config.yaml

# 如果遇到兼容性问题，可以禁用 rule-sets
uv run mihomo2singbox config.yaml --disable-rule-sets

# 调试模式，查看详细转换信息
uv run mihomo2singbox config.yaml --log-level debug

⚠️ 使用注意事项

TUN 模式要求

使用 TUN 模式需要以下条件:

系统管理员权限 (sudo/root)
内核支持 TUN 接口
正确的路由表配置

# Linux 系统检查 TUN 支持
sudo modprobe tun
ls /dev/net/tun

# 以管理员权限运行 sing-box
sudo sing-box run -c singbox_config.json

插件支持说明

插件	状态	转换方式	说明
`obfs` / `simple-obfs`	✅ 支持	→ `obfs-local`	自动转换选项格式
`v2ray-plugin`	✅ 支持	→ `v2ray-plugin`	保持原名，格式化选项
`kcptun`	❌ 不支持	-	显示警告并跳过
其他插件	❌ 不支持	-	显示警告并跳过

规则转换说明

# Mihomo 规则 → Sing-box 规则转换
DOMAIN-SUFFIX,google.com,Proxy     → domain_suffix: ["google.com"], outbound: "Proxy"
GEOIP,CN,DIRECT                    → rule_set: "geoip-cn", outbound: "direct"  
GEOSITE,category-ads,REJECT        → rule_set: "geosite-category-ads", action: "reject"
PROCESS-NAME,chrome,Proxy          → process_name: ["chrome"], outbound: "Proxy"

DNS 配置兼容性

自动升级: 旧版 nameserver → 新版 servers 数组
本地 DNS: 自动添加 local DNS 服务器
DNS 规则: 支持 route、reject 等动作
回退机制: 确保 DNS 解析的可靠性

🐛 故障排除

常见问题

Q: 转换后配置验证失败？

# 检查 sing-box 版本 (需要 1.12.0+)
sing-box version

# 确保使用最新版本
# Linux/macOS
curl -Lo sing-box.tar.gz https://github.com/SagerNet/sing-box/releases/latest/download/sing-box-linux-amd64.tar.gz

Q: TUN 模式无法启动？

# 检查权限
sudo sing-box run -c config.json

# 检查 TUN 支持
cat /dev/net/tun

Q: 插件配置不工作？

警告: 不支持的插件类型 xxx

A: 检查插件名称，当前支持 obfs、simple-obfs、v2ray-plugin。

Q: 规则数量过多导致性能问题？ A: 转换器自动使用 rule-sets 优化大型规则集，无需手动处理。

Q: DNS 解析失败？

# 检查 DNS 配置
jq '.dns' config.json

# 确保有可用的 DNS 服务器
dig @8.8.8.8 google.com

调试模式

# 启用详细日志
uv run mihomo2singbox input.yaml --log-level debug -o debug.json

# 检查特定配置段
jq '.outbounds[0]' debug.json     # 第一个出站配置
jq '.dns.servers' debug.json      # DNS 服务器配置
jq '.route.rules' debug.json      # 路由规则配置
jq '.inbounds' debug.json         # 入站配置

# 验证配置语法
sing-box check -c debug.json

# 测试网络连接
sing-box run -c debug.json --test

错误码说明

错误码	含义	解决方案
1	输入文件不存在	检查文件路径
1	端口范围错误	使用 1-65535 范围内的端口
1	配置解析失败	检查 YAML/JSON 语法

🤝 开发贡献

参与贡献

欢迎贡献代码！请遵循以下步骤：

Fork 项目 - 点击右上角 Fork 按钮
创建分支 - git checkout -b feature/amazing-feature
提交更改 - git commit -m 'Add amazing feature'
推送分支 - git push origin feature/amazing-feature
提交 PR - 在 GitHub 上开启 Pull Request

开发环境设置

# 克隆项目
git clone https://github.com/your-username/mihomo2singbox.git
cd mihomo2singbox

# 使用 uv 设置开发环境
uv sync --dev

# 安装开发工具
uv add --dev ruff black mypy pytest

# 运行测试
uv run pytest

# 代码格式化
uv run ruff check --fix .
uv run black .

# 类型检查
uv run mypy mihomo2singbox/

开发规范

代码质量:

使用 ruff 进行代码检查和格式化
使用 mypy 进行类型检查
编写单元测试覆盖新功能
遵循 PEP 8 代码风格

提交规范:

# 提交格式
git commit -m "type(scope): description"

# 示例
git commit -m "feat(tun): add advanced tun configuration support"
git commit -m "fix(dns): resolve dns server format compatibility issue"
git commit -m "docs(readme): update installation instructions"

分支策略:

main - 稳定版本
develop - 开发版本
feature/* - 新功能开发
bugfix/* - Bug 修复

构建和测试

# 本地构建
uv build

# 安装本地构建的包
pip install dist/mihomo2singbox-*.whl

# 运行测试套件
uv run pytest tests/

# 测试覆盖率
uv run pytest --cov=mihomo2singbox tests/

📚 相关资源

官方文档

📖 Sing-box 官方文档 - 完整配置参考
📖 Sing-box 配置格式 - JSON 配置说明
📖 Mihomo (ClashMeta) 项目 - 原配置格式参考

规则集资源

📦 Sing-geoip 规则集 - IP 地理位置规则
📦 Sing-geosite 规则集 - 域名分类规则
📦 Loyalsoldier 规则集 - 常用规则集

工具生态

社区资源

📈 项目数据

性能指标

基于真实测试配置的转换性能数据：

指标	数值	说明
配置规模	26,924 行 JSON	大型生产环境配置
代理节点	1,463 个节点	Shadowsocks 协议
代理组	21 个选择器	包含自动选择和手动选择
路由规则	25,387 个规则	包含域名、IP、进程规则
转换时间	< 5 秒	在标准硬件上测试
验证状态	✅ 通过	`sing-box check` 验证
文件大小	~800KB	压缩后的 JSON 配置

兼容性矩阵

组件	版本要求	状态	说明
Python	3.11+	✅ 支持	使用现代类型注解
Sing-box	1.12.0+	✅ 支持	完全兼容最新格式
uv	0.1.0+	✅ 推荐	现代包管理器
PyYAML	6.0.2+	✅ 依赖	YAML 解析库

📄 许可协议

本项目采用 MIT 许可证开源。

许可证说明

MIT License

Copyright (c) 2024 mihomo2singbox

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

第三方许可

PyYAML: MIT 许可证
Sing-box: GPL-3.0 许可证 (独立使用)
Mihomo: GPL-3.0 许可证 (独立使用)

🙏 致谢

Sing-box 项目提供了强大的代理工具
Mihomo 项目的 Clash 兼容实现
Claude 4 提供了智能编程辅助，协助完成代码优化和文档编写
所有贡献者和用户的支持

📈 项目状态

开发状态: ✅ 稳定版本
兼容性: ✅ Sing-box 1.12.0+
测试覆盖: ✅ 核心功能测试
文档状态: ✅ 完整文档

📖 使用指南 | 🔧 转换状态 | 🐛 问题反馈

Built with ❤️ by the community • Powered by Claude 4

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
mihomo2singbox		mihomo2singbox
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
CONVERSION_STATUS.md		CONVERSION_STATUS.md
LICENSE		LICENSE
README.md		README.md
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Mihomo2Singbox

✨ 核心特性

📦 安装方式

方式 1: 使用 uv (推荐)

方式 2: 使用 pip

方式 3: 开发环境

🚀 快速开始

基本用法

配置验证和运行

命令行选项

🔧 TUN 功能说明

TUN 模式对比

TUN 配置示例

📋 协议和功能支持

支持的代理协议

转换功能支持

🔧 配置转换示例

输入配置 (Mihomo YAML)

输出配置 (Sing-box JSON)

🎯 版本更新说明 (v0.1.0)

✅ 重要修复

✅ Sing-box 1.12.0+ 兼容性

🔧 技术亮点

📊 性能数据

🛠️ 高级功能

批量转换

自动化脚本

配置文件验证

性能优化建议

⚠️ 使用注意事项

TUN 模式要求

插件支持说明

规则转换说明

DNS 配置兼容性

🐛 故障排除

常见问题

调试模式

错误码说明

🤝 开发贡献

参与贡献

开发环境设置

开发规范

构建和测试

📚 相关资源

官方文档

规则集资源

工具生态

社区资源

📈 项目数据

性能指标

兼容性矩阵

📄 许可协议

许可证说明

第三方许可

🙏 致谢

📈 项目状态

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors 1

Languages

Packages