vscode-settings-link

一份 VS Code 配置，统一所有 Code-OSS 编辑器。

以 VS Code 的 settings.json 作为唯一配置源（Source of Truth），通过**符号链接（Symbolic Link）**让其他基于 VS Code / Code-OSS 的 IDE 实时共享同一份配置：

VS Code/User/settings.json          ← 唯一配置源
        ↓ symlink
Cursor/User/settings.json
Trae/User/settings.json
Kiro/User/settings.json
Windsurf/User/settings.json
Qoder/User/settings.json

修改 VS Code 设置后，其他编辑器自动读取同一个文件——不需要、也不存在「同步命令」这一步。链接建好之后，本工具甚至不需要再运行。

特性

• 一次链接，永久同步：符号链接是操作系统级的，无守护进程、无轮询、无拷贝
• 绝对安全：
  • 替换普通文件前默认自动备份为 settings.json.backup-<时间戳>
  • unlink 只删除符号链接，绝不会误删普通文件
  • 目标已是符号链接且指向别处时，必须经你确认才会替换
• 自动检测已安装的编辑器（Windows / macOS / Linux）
• Windows 权限友好：创建前先实测权限，失败时给出「开发者模式 / 管理员」的具体解决步骤，绝不无提示失败
• dry-run 演练：先看看会发生什么，再决定做不做
• 零运行时依赖：只用 Node.js 内置模块，安装体积小
• Adapter 架构：新增一个 Code-OSS 系编辑器只需几十行配置

安装

npm install -g vscode-settings-link
# 或者免安装直接用
npx vscode-settings-link status

要求 Node.js >= 18.17。

快速开始

vscode-settings-link init

引导式流程：检测已安装的编辑器 → 逐个确认 → 创建链接（原文件先自动备份）→ 完成。

之后在 VS Code 里改任何设置，Cursor / Trae / Kiro / Windsurf / Qoder 立即生效（编辑器运行中时重启一次即可加载）。

命令

| 命令 | 说明 | | --- | --- | | vscode-settings-link | 显示帮助 | | init | 引导式初始化：检测编辑器、逐个确认并创建链接 | | link | 创建符号链接（默认作用于所有已检测编辑器，交互确认） | | unlink | 移除符号链接；绝不删除普通文件；存在备份时询问是否恢复 | | status | 显示各编辑器的安装 / 文件 / 链接状态表 | | doctor | 体检：配置源、链接健康度、Windows 符号链接权限等，发现问题时退出码为 1 |

选项

| 选项 | 说明 | | --- | --- | | --editor <name> | 指定编辑器，可重复：vscode cursor trae trae-cn kiro windsurf qoder（别名：code、codeium） | | --all | 作用于所有已检测到的编辑器 | | --dry-run | 演练：只显示将要执行的操作，不修改任何文件 | | --force | 跳过交互确认（如替换指向他处的符号链接） | | --no-backup | link 替换普通文件前不做备份（默认总是备份） | | --restore | unlink 后直接恢复最近一次备份 | | -h, --help / -v, --version | 帮助 / 版本 |

环境变量 VSL_<ID>_SETTINGS 可覆盖某编辑器的 settings.json 路径（便携版等场景），例如：

VSL_TRAE_SETTINGS="D:\\portable\\Trae\\User\\settings.json" vscode-settings-link link --editor trae

示例

# 先演练一遍，看看会对哪些文件做什么
vscode-settings-link link --all --dry-run

# 只链接 Cursor 和 Trae
vscode-settings-link link --editor cursor --editor trae

# 查看状态
vscode-settings-link status

status 输出示例（链接完成后）：

编辑器    已安装  settings.json  类型      指向                                 正确
VS Code   ✓       ✓              配置源    -                                    -
Cursor    ✓       ✓              symlink   ~\AppData\Roaming\Code\User\...      ✓
Trae      ✓       ✓              普通文件  -                                    ✗
Trae CN   ✓       ✓              普通文件  -                                    ✗
...

# 排查问题（尤其 Windows 权限）
vscode-settings-link doctor

doctor 会在系统临时目录里真实试建一次符号链接来实测权限（立即清理，不碰用户文件）。

link 的安全规则

对每个目标编辑器的 settings.json：

| 目标现状 | 行为 | | --- | --- | | 不存在 | 直接创建符号链接 | | 普通文件 | 先备份为 settings.json.backup-YYYYMMDD-HHMMSS，再替换为符号链接 | | 已正确指向 VS Code | 幂等跳过（重复执行 link 安全） | | 符号链接指向其他位置 | 显示当前指向，交互确认后才替换（--force 跳过确认，非交互环境直接拒绝） | | 悬空符号链接 | 同上，替换时只删除链接本身，不动它指向的文件 |

VS Code 的 settings.json 不存在时（从未启动过 VS Code），会自动创建一个空的 {}——只新建、绝不覆盖。

判断「是否指向 VS Code」使用 realpath 比较，因此即使你的 VS Code settings.json 本身是指向 dotfiles 仓库的符号链接，也能正确识别。

unlink 的安全规则

• 只删除符号链接本身；目标是普通文件时一律拒绝删除，--force 也不例外
• 删除后如果目录里存在备份，会询问是否恢复（交互模式默认恢复；--restore 可在脚本中直接恢复；--force / 非交互则只提示备份位置）
• 备份文件恢复后仍然保留，可反复恢复

支持的编辑器与配置路径

所有路径均从系统环境变量推导（APPDATA / HOME / XDG_CONFIG_HOME），不硬编码用户名。以下路径已在一台装有全部六个 IDE 的 Windows 11 机器上逐一实测。

| 编辑器 | Windows | macOS | Linux | | --- | --- | --- | --- | | VS Code | %APPDATA%\Code\User\settings.json | ~/Library/Application Support/Code/User/settings.json | ~/.config/Code/User/settings.json | | Cursor | %APPDATA%\Cursor\User\settings.json | ~/Library/Application Support/Cursor/User/settings.json | ~/.config/Cursor/User/settings.json | | Trae | %APPDATA%\Trae\User\settings.json | ~/Library/Application Support/Trae/User/settings.json | ~/.config/Trae/User/settings.json | | Trae CN（国内版） | %APPDATA%\Trae CN\User\settings.json | ~/Library/Application Support/Trae CN/User/settings.json | ~/.config/Trae CN/User/settings.json | | Kiro | %APPDATA%\Kiro\User\settings.json | ~/Library/Application Support/Kiro/User/settings.json | ~/.config/Kiro/User/settings.json | | Windsurf | %APPDATA%\Windsurf\User\settings.json | ~/Library/Application Support/Windsurf/User/settings.json | ~/.config/Windsurf/User/settings.json | | Qoder | %APPDATA%\Qoder\User\settings.json | ~/Library/Application Support/Qoder/User/settings.json | ~/.config/Qoder/User/settings.json |

说明：

• Trae 与 Trae CN 是两个独立适配器（trae / trae-cn），同时安装时可用 --editor trae --editor trae-cn 分别链接，status 中也分别显示
• 各 IDE 用户目录下的 ~/.cursor、~/.kiro、~/.qoder 等点目录存放的是扩展、MCP 等 IDE 专属数据，与本工具无关
• 第一版只同步 settings.json，不支持 extensions、keybindings、snippets、MCP、AI Rules、云同步（有意为之，见下方 FAQ）

Windows：符号链接权限

Windows 上创建符号链接需要**「开发者模式」或管理员权限**（这是系统限制，与 Node 版本无关）。没有权限时你会看到类似：

✗ Windows 创建符号链接失败（EPERM）：当前终端没有创建符号链接的权限。
解决方式（任选其一）：
  1. 开启「开发者模式」：Windows 设置 → 系统 → 开发者选项 → 打开「开发人员模式」，然后重试；
  2. 以管理员身份运行终端（右键终端 → 以管理员身份运行）后重试；
  3. 公司电脑可能被组策略禁止创建符号链接，请联系 IT。

工具在真正动手前会先实测权限，权限不足时不做任何修改直接终止。随时可用 vscode-settings-link doctor 检查。

FAQ

Q：VS Code 的 settings.json 支持注释（JSONC），会影响同步吗？ 不会。符号链接对文件内容完全透明，其他编辑器同样支持 JSONC。

Q：备份在哪里？怎么恢复？ 就在 settings.json 同目录下，名为 settings.json.backup-<时间戳>。恢复方式：unlink --restore，或手动复制回去。

Q：想撤出某个编辑器，让它恢复独立配置？ vscode-settings-link unlink --editor cursor，交互确认后可恢复最近备份。

Q：为什么不同步 extensions / keybindings？ 第一版刻意只做 settings.json：扩展列表、快捷键等各 IDE 生态差异较大（尤其 AI 编辑器），盲目共享容易冲突。settings.json 是收益最大、风险最小的起点。

Q：链接后某个编辑器还是旧配置？ 重启一次该编辑器——部分编辑器只在启动时读取 settings.json。

Q：路径不对（便携版/自定义安装）？ 用 VSL_<ID>_SETTINGS 环境变量覆盖，见上方「选项」一节。

Q：如何新增一个 Code-OSS 系编辑器的支持？ 在 src/adapters/index.ts 的 ADAPTER_DESCRIPTORS 里加一条描述（id、名称、别名、候选路径）即可，通用逻辑全部由 BaseEditorAdapter 提供。

开发

npm install        # 安装依赖（仅 devDependencies）
npm run dev        # tsx 直接运行 CLI（如 npm run dev -- status）
npm run typecheck  # TypeScript 严格类型检查
npm test           # 构建 + vitest 全量测试
npm run build      # 编译到 dist/

项目结构

src/
├── cli.ts               # bin 入口：命令分发
├── cli-args.ts          # 零依赖参数解析
├── types.ts             # EditorAdapter 核心契约
├── errors.ts            # 错误类型（含 Windows 权限错误）
├── platform/paths.ts    # 跨平台路径（APPDATA/HOME/XDG，可注入测试）
├── adapters/
│   ├── base-adapter.ts  # 通用实现（检测/链接/备份/恢复）
│   └── index.ts         # 6 个编辑器的注册表
├── core/
│   ├── symlink.ts       # 符号链接创建/错误翻译/权限探测
│   ├── link-manager.ts  # link/unlink 核心状态机
│   ├── status.ts        # 状态收集与表格渲染
│   └── doctor.ts        # 体检
├── prompts/prompter.ts  # 交互确认（非交互环境安全降级）
└── utils/               # 日志、格式化
test/                    # vitest：路径跨平台 / 单元 / CLI 集成测试

测试说明

测试覆盖三种平台（win32/darwin/linux）的路径规则、Adapter 行为、link/unlink 状态机的全部分支、CLI 参数解析，以及通过子进程的 CLI 端到端测试。需要真实符号链接的用例会先探测当前进程权限，无权限（如未开开发者模式的 Windows）时自动跳过，在 macOS / Linux 或已开启开发者模式的 Windows 上全量执行。

License

MIT