@agile-team/vscode-config

@agile-team/vscode-config

团队编辑器配置一键同步工具

一条命令同步 VS Code / Cursor / Windsurf / Kiro 的 settings、keybindings、extensions。 作者维护配置仓库，团队成员一键拉取，支持备份恢复与增量合并。

快速开始

npm i -g @agile-team/vscode-config

vscode-config install              # 交互式选择编辑器和安装模式

更多示例

vscode-config install --editor cursor     # 安装到 Cursor
vscode-config install --editor windsurf   # 安装到 Windsurf
vscode-config install --editor kiro       # 安装到 Kiro
vscode-config install --editor all        # 同时安装到所有编辑器
vscode-config install --mode merge        # 保留个人设置，仅同步团队新增
vscode-config install --dry-run           # 预览，不做任何写入
vscode-config status                      # 检查配置状态
vscode-config restore                     # 一键恢复到安装前

工作流程

配置仓库 (GitHub / Gitee)           团队成员
┌─────────────────────┐            ┌────────────────────┐
│ settings.json       │  ──拉取──▶ │ vscode-config      │
│ keybindings.json    │  双源加速   │ install             │
│ extensions.list     │            │                    │
└─────────────────────┘            │ 1. 下载远程配置     │
         ▲                         │ 2. 写入编辑器目录   │
         │                         │ 3. 安装扩展         │
    作者 push 更新                  │ 4. 验证安装结果     │
    vscode-config upload           └────────────────────┘

命令参考

install — 安装/同步配置

选项	说明
--editor <name>	目标编辑器：vscode / cursor / windsurf / kiro / all / 自定义
--mode <mode>	override（覆盖，默认）或 merge（合并）
--force	跳过备份和交互确认
--dry-run	预览模式，不做任何写入
--source <name>	配置源：github / gitee
--timeout <sec>	扩展安装超时（默认 30 秒）
--extensions-dir <path>	离线 .vsix 目录（内网环境）
-v	显示详细诊断日志

upload — 上传本地配置到团队仓库

选项	说明
--mode <mode>	override（覆盖）或 merge（合并）
--source <name>	github / gitee / all（默认）
--editor <name>	读取哪个编辑器的本地配置
--repo <path>	指定本地已 clone 的配置仓库路径

download-extensions — 批量下载 .vsix（管理员用）

选项	说明
--output <dir>	输出目录（默认 vsix-cache）
--force	强制重新下载所有扩展（覆盖已有文件）
--merge	只增不删 — 保留目录中不在列表里的 .vsix

默认覆盖模式: 以 extensions.list 为准，自动删除目录中已废弃的 .vsix。

status / restore / clean

命令	说明
vscode-config status	检查编辑器版本、配置文件、已装扩展、备份
vscode-config restore	恢复备份（多个可交互选择）
vscode-config restore --list	列出所有可用备份
vscode-config restore --backup <path>	恢复指定路径的备份
vscode-config clean	清理 30 天前的旧备份
vscode-config clean --older-than <days>	指定清理天数

以上命令均支持 --editor <name> 指定编辑器。

安装模式

模式	行为	场景
覆盖（默认）	完全替换 settings / keybindings，保证团队一致	新机器初始化、重置为团队标准
合并 --mode merge	深度合并，同名 key 覆盖，独有 key 保留	已有个人配置，只同步团队新增

两种模式都会自动备份当前配置，可随时 restore 回滚。

多编辑器支持

内置 VS Code、Cursor、Windsurf、Kiro 四种编辑器，支持通过配置文件自定义更多编辑器（如 Trae、Zed 等）。

• 不带 --editor 参数时交互式选择，自动检测已安装的编辑器
• --editor all 同时安装到所有已检测编辑器
• 未检测到的编辑器会置灰不可选
• 自定义编辑器在 .vscode-configrc.json 的 editors 字段中注册

为什么不用编辑器自带的「导入配置」？ 因为那是一次性操作。本工具支持持续同步 — 团队配置更新后再跑一次 install 即可。

扩展安装机制

核心原理：绕过 code.cmd 脚本，直接调用 Electron + cli.js：

ELECTRON_RUN_AS_NODE=1  Code.exe  cli.js  --install-extension <ext-id>

• 零弹窗 — ELECTRON_RUN_AS_NODE=1 以 Node 模式运行 CLI
• 输出可靠 — stdout 直接返回安装结果
• 逐个安装 + 最终验证 — 每个扩展独立安装后用 --list-extensions 核实
• 跨平台 — 自动检测 Windows / macOS / Linux 安装路径
• 安全 — 扩展 ID 格式校验，防止命令注入
• 只增不减 — 绝不会卸载已有扩展

备份与恢复

每次安装前自动备份 settings.json、keybindings.json、snippets。

vscode-config restore             # 恢复最新备份
vscode-config restore --list      # 列出所有备份
vscode-config clean --older-than 7 # 清理 7 天前的旧备份

备份存储位置

编辑器	Windows	macOS	Linux
VS Code	%APPDATA%\Code\User\backup-*\	~/Library/Application Support/Code/User/backup-*/	~/.config/Code/User/backup-*/
Cursor	%APPDATA%\Cursor\User\backup-*\	~/Library/Application Support/Cursor/User/backup-*/	~/.config/Cursor/User/backup-*/
Windsurf	%APPDATA%\Windsurf\User\backup-*\	~/Library/Application Support/Windsurf/User/backup-*/	~/.config/Windsurf/User/backup-*/
Kiro	%APPDATA%\Kiro\User\backup-*\	~/Library/Application Support/Kiro/User/backup-*/	~/.config/Kiro/User/backup-*/

网络与配置源

双源自动切换：GitHub → Gitee，国内用户无需配置。

vscode-config install --source gitee --timeout 120  # 强制国内源 + 慢网超时

配置文件

其他团队使用自建配置仓库时，在项目根目录或用户 home 目录创建 .vscode-configrc.json，无需 fork 修改源码：

{
  // 配置源 — 替代默认的 GitHub / Gitee
  "sources": [
    {
      "name": "公司内网",
      "baseUrl": "https://git.internal.com/raw/team-config/main",
    },
  ],

  // 仓库地址 — upload 命令使用
  "repos": {
    "primary": "[e-mail]:team/editor-config.git",
  },

  // 自定义编辑器 — 内置 4 个之外的新编辑器
  "editors": {
    "trae": {
      "label": "Trae",
      "configDirName": "Trae",
      "cliName": "trae",
      "winExeName": "Trae.exe",
      "macAppNames": ["Trae.app"],
      "linuxExeName": "trae",
      "website": "https://trae.ai/",
    },
  },
}

查找顺序: 项目目录 .vscode-configrc.json → 用户 home ~/.vscode-configrc.json → 内置默认值

优先级链: 环境变量 > 项目配置文件 > home 配置文件 > 内置默认值

环境变量

环境变量优先级最高，可覆盖配置文件和默认值：

环境变量	默认值	说明
VSCODE_CONFIG_GITHUB_URL	https://raw.githubusercontent.com/ChenyCHENYU/vscode-config/main	GitHub 配置源 raw 地址
VSCODE_CONFIG_GITEE_URL	https://gitee.com/ycyplus163/vscode-config/raw/main	Gitee 配置源 raw 地址
VSCODE_CONFIG_REPO_GITHUB	[e-mail]:ChenyCHENYU/vscode-config.git	upload 命令使用的 GitHub 仓库地址
VSCODE_CONFIG_REPO_GITEE	[e-mail]:ycyplus163/vscode-config.git	upload 命令使用的 Gitee 仓库地址

# 示例：临时指向自建仓库（无需创建配置文件）
VSCODE_CONFIG_GITHUB_URL=https://raw.githubusercontent.com/your-org/config/main vscode-config install

所有环境变量和配置文件均为可选，不设置时使用默认地址。

安全测试指南

担心覆盖现有配置？按照以下流程零风险试用：

1. vscode-config install --dry-run     # 预览，不写入任何文件
2. vscode-config install               # 安装（自动备份）
3. vscode-config restore               # 不满意？一键恢复

扩展只增不减，不会卸载已有扩展。如需手动卸载请在编辑器扩展面板操作。

常见场景

# 新人入职
npm i -g @agile-team/vscode-config && vscode-config install

# 团队配置更新后同步
vscode-config install --force

# 保留个人偏好只同步团队新增
vscode-config install --mode merge

# 网络差
vscode-config install --source gitee --timeout 120

# 云桌面 / 内网
npm i -g @agile-team/vscode-config @agile-team/vscode-config-extensions
vscode-config install

内网 / 离线 / 云桌面

配置文件内置离线兜底（defaults/），远程不可用时自动读取包内配置。

扩展安装依赖编辑器 marketplace，不可用时工具会自动降级：

扩展安装优先级：
  1. --extensions-dir 参数          ← 显式指定 .vsix 目录
  2. VSCODE_CONFIG_EXTENSIONS_DIR   ← 环境变量
  3. @agile-team/vscode-config-extensions ← 伴侣 npm 包（自动检测）
  4. 在线 marketplace              ← 默认

三种场景

场景	npm	marketplace	方案
外网本地	✅	✅	直接 vscode-config install
内网本地	✅	❌	在有网时先执行一次 install，扩展本地持久保留
云桌面内网	✅	❌	安装伴侣包，主工具自动检测

云桌面一键安装（推荐）

# 一条命令搞定，无需额外配置
npm i -g @agile-team/vscode-config @agile-team/vscode-config-extensions
vscode-config install

主工具自动发现伴侣包中的 .vsix 文件，无需 --extensions-dir 参数。

注意: 伴侣包不含 AI 类扩展（tongyi-lingma / copilot-chat / roo-cline / cline 等），因为它们在内网无法连接 AI 服务。

管理员维护

伴侣包发布时自动拉取远程最新 extensions.list，单一数据源，零手动维护：

# 更新远程扩展列表（管理员本地 → 云端）
vscode-config upload

# 发布伴侣包（自动同步远程 list → 下载 .vsix → 清理废弃）
cd packages/vscode-config-extensions
npm version patch && npm publish --access public

独立下载 .vsix（不依赖伴侣包）：

vscode-config download-extensions --output ./vsix-cache           # 覆盖模式（默认）
vscode-config download-extensions --output ./vsix-cache --merge   # 只增不删
vscode-config download-extensions --output ./vsix-cache --force   # 全量重下

故障排除

症状	解决方案
XXX 未检测到	安装对应编辑器并确保 CLI 命令在 PATH 中
扩展安装超时	--timeout 120 或 --source gitee
所有扩展均失败	可能处于内网，参考「内网 / 离线 / 云桌面」章节
部分扩展失败	工具会输出手动安装命令，复制执行即可
需要回滚	vscode-config restore
想看详细日志	vscode-config install --force -v

系统要求

依赖	版本
Node.js	>= 16.7
Git	已安装
编辑器	VS Code / Cursor / Windsurf / Kiro 至少一个

vscode-config status  # 一键检查环境

配置仓库维护

团队配置存放在独立仓库，结构如下：

vscode-config/
├── settings.json       # 编辑器设置
├── keybindings.json    # 快捷键
└── extensions.list     # 扩展列表（每行一个 ID，# 开头为注释）

作者修改后 push 到 GitHub / Gitee，团队成员 vscode-config install 即可同步。

也可以用 CLI 直接上传：

vscode-config upload                      # 推送到 GitHub + Gitee
vscode-config upload --editor windsurf    # 上传 Windsurf 的配置

链接

• 配置仓库 — 团队共享配置
• 问题反馈 — Bug & 建议
• npm 主包 — 安装
• npm 伴侣包 — 离线扩展
• CHANGELOG — 版本记录

MIT License · Made by CHENY