hostx — hosts 文件管理 CLI

hostx 是一个命令行工具，用于通过分组管理系统的 hosts 文件条目。支持多分组、启用/禁用、自动备份与恢复。

安装

npm install -g hostx

或从源码运行：

npm run dev -- <command>    # 开发模式（tsx 直接运行）
npm run build               # 编译到 dist/
npm start -- <command>      # 运行编译后的版本

工作流程

hostx 采用配置-应用分离的设计：

host add / group enable  →  修改 ~/.hostx/config.json（无需权限）
apply                    →  写入系统 hosts 文件（需要管理员/sudo 权限）

先通过 host add、host disable 等命令编辑配置，确认无误后执行 apply 一次性写入系统。

命令速查

| 命令 | 别名 | 说明 | |------|------|------| | host add <domain> <ip> [extra...] | ha | 添加 host 记录（支持批量） | | host remove <domain> | hr | 删除 host 记录 | | host update <domain> | hu | 修改 host 记录 | | host list | hl | 列出所有 host 记录 | | host enable <domain> | he | 启用 host 记录 | | host disable <domain> | hd | 禁用 host 记录 | | group add <name> | ga | 创建分组 | | group remove <name> | gr | 删除分组 | | group rename <old> <new> | gn | 重命名分组 | | group list | gl | 列出所有分组 | | group show <name> | gs | 查看分组详情 | | group enable <name> | ge | 启用分组 | | group disable <name> | gd | 禁用分组 | | apply | a | 写入系统 hosts 文件 | | backup | b | 手动备份 hosts 文件 | | restore [file] | r | 恢复 hosts 文件 | | doctor | d | 诊断系统状态 |

分组管理

分组用于对 host 条目进行逻辑隔离。分组默认是禁用状态，只有启用后的分组才会被 apply 写入。

# 创建分组
hostx group add dev
hostx ga dev

# 启用分组（否则 apply 不会写入）
hostx group enable dev
hostx ge dev

# 禁用分组
hostx group disable dev
hostx gd dev

# 查看所有分组
hostx group list
hostx gl

# 查看分组详情（包含其中的 host 条目）
hostx group show dev
hostx gs dev

# 重命名分组
hostx group rename dev staging
hostx gn dev staging

# 删除分组
hostx group remove dev
hostx gr dev

Host 条目管理

添加

# 单个添加到指定分组
hostx host add example.com 127.0.0.1 --group dev
hostx ha example.com 127.0.0.1 -g dev

# 批量添加（后面跟 domain-ip 对）
hostx ha a.com 1.1.1.1 b.com 2.2.2.2 c.com 3.3.3.3 -g dev

# 不指定分组，自动添加到 default 分组（自动创建）
hostx ha example.com 127.0.0.1

# 批量添加到 default
hostx ha a.com 1.1.1.1 b.com 2.2.2.2

# 添加备注（批量时备注仅对第一个 domain 生效）
hostx ha example.com 127.0.0.1 -g dev -c "my dev server"

查看

# 列出所有 host
hostx host list
hostx hl

# 按分组过滤
hostx hl -g dev

修改

# 修改 IP
hostx host update example.com --ip 192.168.1.100
hostx hu example.com --ip 192.168.1.100

# 修改备注（传空字符串清除备注）
hostx hu example.com -c "new comment"

# 指定分组（当域名存在于多个分组时必需）
hostx hu example.com --ip 1.2.3.4 -g dev

删除

# 删除（域名唯一时自动识别分组）
hostx host remove example.com
hostx hr example.com

# 指定分组（域名存在于多个分组时必需）
hostx hr example.com -g dev

启用/禁用

禁用后的 host 条目不会被 apply 写入 hosts 文件，但保留在配置中。

hostx host disable example.com
hostx hd example.com

hostx host enable example.com
hostx he example.com

应用与回滚

写入系统 hosts 文件

# 需要管理员/sudo 权限
hostx apply
hostx a

# 强制写入，自动去重（相同 domain 保留最后一个）
hostx a --force

apply 会在写入前自动创建备份。

备份与恢复

# 手动备份
hostx backup
hostx b

# 恢复最新备份（恢复前也会自动创建备份）
hostx restore
hostx r

# 恢复指定备份文件
hostx restore ~/.hostx/backups/hosts-2024-01-01.bak

备份文件存储在 ~/.hostx/backups/hosts-*.bak。

诊断

hostx doctor
hostx d

输出系统状态表，包括：

• 操作系统平台
• hosts 文件路径及读写权限
• 配置文件路径
• 分组数量
• 域名冲突数量及详情

配置文件

配置文件位于 ~/.hostx/config.json，格式如下：

{
  "version": 1,
  "groups": {
    "default": {
      "enabled": true,
      "hosts": [
        { "domain": "example.com", "ip": "127.0.0.1", "enabled": true, "comment": "my site" }
      ]
    }
  }
}

hosts 文件标记

apply 写入系统 hosts 文件时，会在文件中插入标记块：

# hostx start
127.0.0.1 example.com # group: dev my site
# hostx end

• # hostx start / # hostx end 之间的内容由 hostx 管理
• 多次 apply 会替换标记块内的内容，不会重复追加
• 标记块外的自定义 hosts 条目不受影响

域名冲突处理

当同一个域名在多个已启用的分组中存在时，apply 会报错并列出冲突详情：

Host conflicts found:
example.com exists in groups: dev, staging

解决方案：

1. 禁用其中一个分组：hostx gd staging
2. 删除重复条目：hostx hr example.com -g staging
3. 使用 --force 强制去重（保留最后一个）

完整示例

# 1. 创建并启用分组
hostx ga dev
hostx ge dev

# 2. 添加 host 条目
hostx ha myapp.local 127.0.0.1 -g dev -c "local dev"
hostx ha api.myapp.local 127.0.0.1 -g dev

# 3. 查看配置
hostx hl

# 4. 应用（需要管理员权限）
sudo hostx a

# 5. 验证
cat /etc/hosts
# Windows: type C:\Windows\System32\drivers\etc\hosts