配置切换器 · 用户操作手册

ConfigSwitch — macOS Configuration File Switcher

基于实际 hosts 与 Maven 配置场景演示

📋 目录导航

  1. 应用概述
  2. 启动与主界面
  3. 实战一：创建 hosts 配置组
  4. 添加 hosts 配置项
  5. 编辑 hosts 配置内容
  6. 覆盖模式切换
  7. 追加模式（多选合并）
  8. 菜单栏快速切换
  9. 实战二：Maven 配置管理
  10. Maven 配置切换验证
  11. 语言切换
  12. 配置组/项管理
1

应用概述

配置切换器（ConfigSwitch）是一款 macOS 平台的配置文件快速切换管理工具， 帮助用户轻松管理和切换不同环境下的配置文件，避免手动备份修改的繁琐操作。

核心特性

配置组管理按文件类型分组管理（hosts / maven / nginx 等）
多配置项支持同一配置组下可创建多套配置（local / dev / prod）
两种写入模式覆盖模式（单选互斥）和追加模式（多选合并）
菜单栏快捷切换无需打开主窗口即可一键切换
11 种语言实时切换，无需重启应用
浅色/深色主题支持跟随系统、强制浅色、强制深色

适用场景

💡 安全机制：应用通过 macOS Security-Scoped Bookmark 机制访问用户选定的文件， 确保在沙盒环境下安全持久访问。首次使用需用户在系统文件选择器中授权目标文件。
2

启动与主界面

启动应用

双击应用图标启动「配置切换器」。启动后应用会显示在 Dock 栏和顶部状态栏中。

主界面
图 1：主界面 — 选中 hosts 配置组，首次使用触发文件授权弹窗

三栏式布局

主界面布局
图 2：三栏布局 — hosts 组的详情视图，右侧显示当前 /etc/hosts 文件内容
📌 窗口行为：点击窗口左上角红色关闭按钮不会退出应用，应用会隐藏到状态栏中。 点击 Dock 图标或状态栏图标可重新显示窗口。
3

实战一：创建 hosts 配置组

本节以创建 /etc/hosts 配置组为例，演示完整的创建流程。

点击「添加配置」按钮
在主窗口标题栏右侧点击 + 按钮，打开「添加配置」弹窗。
填写配置信息
  • 配置名称：输入 hosts
  • 配置文件路径：点击右侧文件夹图标，通过系统文件选择器选择 /etc/hosts
  • 写入模式：选择「覆盖」覆盖模式（同一时间只启用一个配置项）
选择文件
图 3：系统文件选择器 — 在 /etc 目录中选择 hosts 文件
保存配置组
点击「保存」按钮，配置组出现在左侧边栏并自动选中。 系统会创建 Security-Scoped Bookmark 用于后续持续访问。
配置组创建完成
图 4：hosts 配置组创建完成 — 右侧显示当前 /etc/hosts 的内容
⚠️ 授权说明：如果首次写入时文件授权已失效，应用会弹出「请求授权」对话框， 引导用户重新选择目标文件（如图 1 所示）。
4

添加 hosts 配置项

在 hosts 配置组下创建多个配置项，用于不同环境的快速切换。

创建「local」配置项

点击中间栏的「+」按钮
在 hosts 组的中间栏顶部，点击 + 按钮添加配置项。
添加local
图 5：添加配置项弹窗 — 创建名为「local」的配置项
输入配置环境名称并保存
输入名称 local，点击「保存」。新配置项出现在列表中，右侧编辑器自动加载该条目内容。

创建「dev」配置项

同样的步骤，再创建一个名为 dev 的配置项。

添加dev
图 6：添加第二个配置项 — 名为「dev」
配置项列表
图 7：hosts 组下已有 local 和 dev 两个配置项
💡 快速添加：也可通过右键菜单（在中间栏空白处右键 →「添加」）新增配置项。
5

编辑 hosts 配置内容

每个配置项存储独立的配置内容。下面以编辑 hosts 的两个配置项为例。

设置 local 配置内容

选中 local 配置项
在中间栏点击「local」，右侧编辑器显示该项存储的内容。
编辑内容并保存
在编辑器中输入 local 环境的 hosts 内容，如： 
127.0.1    localhost
::1              localhost
内容修改后标题栏会显示橙色 ● 标记。点击保存按钮（或 Cmd+S）保存。
编辑local
图 8：编辑 local 配置项内容 — 橙色圆点表示未保存修改

设置 dev 配置内容

选中 dev 配置项，编辑为 dev 环境的 hosts 内容：

127.0.1    localhost
::1              localhost
127.0.0.1    www.test.com
编辑dev
图 9：编辑 dev 配置项内容 — 添加自定义域名解析
📌 保存规则：
  • 配置项未启用时：内容仅保存到应用内部（Core Data），不写入磁盘文件
  • 配置项已启用时：会弹出确认对话框，询问是否同步更新磁盘文件
6

覆盖模式切换 单选互斥

覆盖模式下，同一时间只有一个配置项生效。切换启用项时，目标文件被该配置项内容完全覆盖。

场景验证

启用 local 配置项
点击 local 项右侧的圆形开关图标，切换为蓝色启用状态。 此时 /etc/hosts 文件被写入 local 配置的内容。
启用local
图 10：启用 local 配置项 — 终端 cat /etc/hosts 验证已写入
切换到 dev 配置项
点击 dev 项的圆形开关。在覆盖模式下，系统自动禁用 local 项， /etc/hosts 被 dev 配置的内容（含 www.test.com 解析）覆盖。
切换dev
图 11：切换到 dev 配置 — local 自动取消，hosts 文件已更新
终端验证
在终端执行 cat /etc/hosts，确认文件内容为 dev 配置的内容。 进一步可执行 ping www.test.com 验证域名解析是否生效。
ping验证
图 12：终端验证 — ping www.test.com 成功，自定义域名解析生效
⚠️ 注意：覆盖模式切换操作会立即写入磁盘文件。请确保配置项内容正确后再启用。
7

追加模式（多选合并）多选合并

追加模式下可同时启用多个配置项，所有启用项的内容按顺序合并写入目标文件。

将 hosts 切换为追加模式

编辑配置组
右键点击左侧的「hosts」配置组，选择「编辑」。
右键菜单
图 13：配置组右键菜单 — 编辑、删除、消权
切换写入模式
在编辑弹窗中，将「写入模式」从「覆盖」切换为「追加」，点击保存。
切换追加模式
图 14：编辑配置弹窗 — 将写入模式切换为「追加」

同时启用 local 和 dev

启用多个配置项
在追加模式下，local 和 dev 两个项均可独立启用（蓝色勾选）。 系统将两项内容合并后写入 /etc/hosts。
追加模式验证
图 15：追加模式 — local 和 dev 同时启用，hosts 文件包含完整内容
💡 合并规则：各启用项的内容按列表顺序合并，以换行符分隔。 修改任一启用项内容并保存后，系统会重新合并写入。
9

实战二：Maven 配置管理

本节以管理 Maven 的 settings.xml 为例，演示另一种常见使用场景。

创建 Maven 配置组

添加 maven 配置组
点击「+」按钮，创建新配置组：
  • 配置名称：maven
  • 配置文件路径：~/Users/ming/.m2/settings.xml
  • 写入模式：覆盖模式
创建maven组
图 18：创建 maven 配置组 — 关联 ~/.m2/settings.xml
maven组详情
图 19：maven 配置组详情 — 右侧显示当前 settings.xml 内容

创建 Maven 配置项

添加「aliyun」配置项
在 maven 组下添加第一个配置项 aliyun， 写入阿里云 Maven 镜像配置内容（包含 mirror 和 server 配置）。
aliyun配置项
图 20：maven 组下已有 aliyun 配置项
添加「company」配置项
再添加 company 配置项，写入公司内部 Maven 仓库配置。
company配置项
图 21：添加 company 配置项 — 编辑默认 settings.xml 作为公司配置模板
10

Maven 配置切换验证

在 maven 配置组中，可以通过启用开关或菜单栏切换不同的 Maven 仓库配置。

启用 aliyun 配置
点击 aliyun 项的启用开关，settings.xml 被写入阿里云镜像配置。 此时 Maven 命令（如 mvn compile）将使用阿里云镜像加速下载。
切换到 company 配置
点击 company 项的启用开关，覆盖模式下自动禁用 aliyun 项。 settings.xml 被替换为公司内部仓库配置。
验证效果
执行 Maven 构建命令，观察依赖下载源是否为预期的仓库地址， 确认切换生效。
💡 典型工作流：
1. 开发时启用 aliyun 配置加速依赖下载
2. 发布时启用 company 配置使用公司内部仓库
3. 临时需要公网下载时，可再添加一个 default 配置项
11

语言与外观切换

切换应用语言

应用支持 11 种语言实时切换，无需重启：

操作路径：屏幕顶部菜单栏 →「Language」→ 选择目标语言

切换外观主题

支持三种外观模式：

操作路径：屏幕顶部菜单栏 →「Appearance」→ 选择模式

12

配置组/项管理

配置组管理（左侧栏右键）

配置组管理
图 22：配置组右键菜单

配置项管理（中间栏右键）

⚠️ 二次确认：所有删除操作均会弹出确认对话框，确认后不可恢复。
附

附录：快速上手指南

首次使用配置切换器的用户，建议按以下顺序快速熟悉所有功能：

  1. 创建 hosts 配置组：选择 /etc/hosts，测试文件授权流程
  2. 添加配置项：创建 local 和 dev 两个配置项，分别录入不同的 hosts 内容
  3. 覆盖模式切换：在 local / dev 之间切换，用 cat /etc/hosts 和 ping www.test.com 验证
  4. 追加模式测试：将 hosts 组改为追加模式，同时启用两项，验证合并写入
  5. 创建 maven 配置组：关联 ~/.m2/settings.xml，创建 aliyun 和 company 配置项
  6. 菜单栏切换：通过菜单栏快速切换 hosts 和 maven 的配置项
  7. 语言/外观：切换 2-3 种语言和外观模式
  8. 删除与确认：删除一个配置项，验证二次确认对话框
📌 测试文件准备：建议在使用前准备好以下文件以确保测试顺利：
· /etc/hosts（系统文件，需授权访问）
· ~/.m2/settings.xml（Maven 配置文件，需提前准备）

配置切换器 ConfigSwitch · 用户操作手册

macOS Configuration File Quick Switch Tool