# cb-hostsbox

**Repository Path**: rexlevin/cb-hostsbox

## Basic Information

- **Project Name**: cb-hostsbox
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HostsBox

基于 [CanBox平台](https://canbox-io.github.io/canbox-pages/) 的跨平台的 hosts 文件管理工具，让你轻松管理多套 hosts 配置、一键切换生效，无需手动编辑系统文件。

## 功能特性

### 配置管理

- **多配置管理**：创建任意数量的 hosts 配置（如开发环境、测试环境、生产环境），相互独立、随时切换
- **默认配置**：内置一份"默认配置"，始终作为 hosts 的基础内容生效
- **一键激活/失效**：通过开关在任意配置间切换，无需删除或重写
- **批量操作**：支持多选后批量生效、批量失效、批量删除
- **自动保存**：编辑内容时自动保存（防抖 800ms），无需手动点击保存

### 系统集成

- **只读查看系统 hosts**：直接显示当前 `/etc/hosts`（Windows 为 `C:\Windows\System32\drivers\etc\hosts`）的原始内容
- **提权写入**：应用 hosts 时自动弹出系统提权对话框，确认后写入
- **跨平台支持**：Windows、macOS、Linux 全平台支持
- **打开目录**：一键打开 hosts 文件所在目录

### 编辑器

- **语法高亮**：基于 CodeMirror 6，hosts 格式高亮显示
- **搜索替换**：支持 `Ctrl+F` 搜索、`Ctrl+H` 替换
- **快捷导航**：`Ctrl+G` 跳转搜索结果、`Ctrl+D` 选中当前词、`Ctrl+Home/End` 跳转文件首尾
- **深色主题**：内置 One Dark 主题，长时间编辑不疲劳

### 其他

- **界面缩放**：支持 `Ctrl+滚轮`、`Ctrl+=`、`Ctrl+-` 调整界面大小（0.8x ~ 1.5x），设置自动持久化
- **窗口状态记忆**：记住窗口位置和大小，下次打开自动恢复
- **首次备份**：首次运行时自动备份当前 hosts 到文档目录，避免误操作丢失

## 快捷键

### 界面操作

| 快捷键              | 功能                    |
| ------------------- | ----------------------- |
| `Ctrl` + `N`    | 新增自定义配置          |
| `Ctrl` + `S`    | 保存当前编辑内容        |
| `Ctrl` + `滚轮` | 缩放界面（0.8x - 1.5x） |
| `Ctrl` + `=`    | 放大界面                |
| `Ctrl` + `-`    | 缩小界面                |
| `Esc`             | 关闭搜索/替换面板       |

### 编辑器操作（CodeMirror）

| 快捷键                       | 功能                 |
| ---------------------------- | -------------------- |
| `Ctrl` + `F`             | 搜索                 |
| `Ctrl` + `H`             | 搜索并替换           |
| `Ctrl` + `G`             | 跳转到下一个搜索结果 |
| `Ctrl` + `Shift` + `G` | 跳转到上一个搜索结果 |
| `Ctrl` + `D`             | 选中当前词           |
| `Ctrl` + `Home`          | 跳转到文件开头       |
| `Ctrl` + `End`           | 跳转到文件末尾       |

## 使用指南

### 创建配置

1. 点击左侧"自定义配置"后的 **+** 按钮（或按 `Ctrl+N`）
2. 输入配置名称（如"开发环境"），点击确定
3. 在右侧编辑器中输入 hosts 内容
4. 内容会自动保存，也可按 `Ctrl+S` 手动保存

### 启用配置

- 点击配置右侧的开关，将其切换为"激活"状态
- 系统会弹出提权对话框，确认后该配置内容将追加到系统 hosts
- 多个激活的配置会按顺序合并写入

### 编辑默认配置

1. 点击左侧"默认"
2. 点击"编辑"按钮进入编辑模式
3. 修改内容后点击"保存生效"，会同时保存并应用到系统

### 批量操作

- 勾选多个配置前的复选框
- 底部出现批量操作栏，可一键全部生效、全部失效、全部删除

### hosts 文件格式

每行格式为 `IP地址 域名1 域名2 ...`，以 `#` 开头为注释：

```
# 本地回环
127.0.0.1 localhost

# 开发环境
10.0.0.1 dev.example.com api.example.com
```

## 权限说明

写入系统 hosts 文件需要管理员/root 权限，应用时会弹出系统提权对话框：

- **Linux**：pkexec（GUI 提权）
- **macOS**：osascript（administrator privileges）
- **Windows**：PowerShell（-Verb RunAs）

如果取消提权，hosts 不会变更，配置状态会自动恢复。

## 注意事项

- 修改 hosts 后可能需要重启浏览器或刷新 DNS 缓存才能生效
- 某些 DNS 缓存服务需要等待 TTL 过期
- hosts 文件格式错误可能导致系统解析异常
- 建议在重要操作前先备份 hosts 文件（首次运行时已自动备份到文档目录）

## 开发

### 环境要求

- Node.js >= 24
- Electron >= 41

### 命令

```bash
# 安装依赖
npm install

# 启动开发模式（需先启动 vite dev server）
npm run dev    # 前端开发服务器
npm run start  # Electron 开发模式（detach 模式打开 devtools）

# 构建生产版本
npm run build

# 打包分发
npm run dist   # 使用 electron-builder 打包
```

## 许可证

Apache-2.0