Skip to Content
🚀 vsync v1.0 发布！轻松同步你的 AI 工具。 在 GitHub 上 Star 我们
文档常见问题

常见问题

关于使用 vsync 的常见问题和解答。

一般问题

我应该使用哪个工具作为源？

我们推荐 Claude Code，因为：

  • 功能最完整（Skills、MCP、Agents、Commands）
  • 简洁的 JSON 格式
  • 文档完善
  • 积极开发

但是，您可以使用任何支持的工具作为源。选择取决于：

  • 您主要使用哪个工具编辑配置
  • 哪个工具目前有最完整的设置
  • 团队偏好和工作流程

vsync 会覆盖我现有的配置吗？

默认情况下，Safe 模式只创建和更新——从不删除。您的目标工具中的现有配置将更新以匹配源，但除非使用 --prune 模式，否则不会删除任何内容。

重要：直接在目标工具中所做的更改将在下次同步时被覆盖。始终在源工具中编辑。

如果我直接在目标工具中编辑配置会怎样？

目标工具中的更改将在下次同步时被覆盖。vsync 使用单向同步模型：

Source（您的编辑） → Targets（自动更新）

最佳实践：始终在源工具中编辑，或使用 import 从另一个项目拉取更改。

如何切换我的源工具？

只需重新运行 init 命令：

vsync init
# 选择不同的源工具

然后同步以使用新源更新所有目标。

它支持 monorepos 吗？

**是的！**每个项目可以有自己的 .vsync.json。用户级配置（~/.vsync.json）在所有项目中全局工作。

示例结构：

monorepo/
├── packages/
│   ├── frontend/
│   │   └── .vsync.json  # 前端特定配置
│   └── backend/
│       └── .vsync.json  # 后端特定配置
└── .vsync.json          # Monorepo 根配置

将 .vsync.json 提交到 git 安全吗？

**是的！**配置文件包含：

  • 工具名称
  • 同步偏好
  • 无密钥或凭证

带密钥的 MCP 配置应使用环境变量如 ${API_KEY}，这是安全提交的。

我可以双向同步吗？

不，vsync 是单向的（源 → 目标）。这是故意的，以维护清晰的配置源。

要切换方向：

  1. 运行 vsync init
  2. 选择不同的源工具
  3. 同步以更新目标

配置问题

Project 层级和 User 层级有什么区别？

Project 层级 (.vsync.json)：

  • 通过 git 共享的团队配置
  • 项目特定的 Skills 和集成
  • 范围限定到一个项目目录

User 层级 (~/.vsync.json)：

  • 个人全局配置
  • 在所有项目中工作
  • 不与团队共享
  • 适合个人偏好和全局 Skills

我可以同时使用 project 和 user 层级配置吗？

是的！它们独立运行：

# 同步项目配置
vsync sync
 
# 同步用户配置
vsync sync --user

项目配置不会覆盖用户配置——它们是独立的层级。

如何排除特定工具？

只需不要在 target_tools 中包含它们：

{
  "source_tool": "claude-code",
  "target_tools": ["cursor"]  // 只同步到 Cursor，不同步到 OpenCode
}

同步行为问题

Safe 模式和 Prune 模式有什么区别？

Safe 模式（默认）：

源: A, B, C
目标: A, B, D
结果: A, B, C, D  (保留 D)

Prune 模式：

源: A, B, C
目标: A, B, D
结果: A, B, C  (删除 D)

我如何知道更改了什么？

使用 plan 命令查看详细预览：

vsync plan

或使用 --dry-run 与 sync：

vsync sync --dry-run

两者都会准确显示将被创建、更新、删除或跳过的内容。

我可以在应用更改之前查看吗？

是的！默认情况下，vsync sync 会显示计划并请求确认：

📋 同步计划 (Safe 模式)

cursor:
  CREATE: 1 项
  UPDATE: 2 项

? 继续同步？ (Y/n)

使用 -y/--yes 跳过确认（用于自动化）。

MCP 问题

为什么每个工具中的环境变量看起来不同？

每个工具都有自己的变量插值语法：

工具语法示例
Claude Code${VAR}${API_KEY}
Cursor${env:VAR}${env:API_KEY}
OpenCode{env:VAR}{env:API_KEY}
Codex无插值仅直接值

vsync 自动在这些格式之间转换。

vsync 会暴露我的密钥吗？

不会！ vsync：

  • 从不展开环境变量
  • 原样保留变量引用
  • 仅在格式之间转换语法
  • 不读取实际环境值

示例：

// 同步前（源）
{ "TOKEN": "${API_TOKEN}" }
 
// 同步后（目标）
{ "TOKEN": "${env:API_TOKEN}" }  // 引用已保留，未展开

我可以为环境变量使用默认值吗？

可以，但有限制：

// Claude Code（支持默认值）
{
  "env": {
    "PORT": "${PORT:-3000}"
  }
}

注意：Cursor 和 OpenCode 不支持默认值，因此它们将被转换为简单的变量引用：

// 同步到 Cursor（默认值语法丢失）
{
  "env": {
    "PORT": "${env:PORT}"
  }
}

Skills 和 Agents 问题

我可以同步带有自定义文件的 Skills 吗？

可以！ Skills 可以包含多个文件：

my-skill/
├── SKILL.md           # 主技能文件
├── template.md        # 支持文件
├── examples/          # 支持目录
│   └── good.md
└── scripts/
    └── helper.sh

所有文件都会一起同步（或如果启用则符号链接）。

Skills 和 Agents 有什么区别？

  • Skills：可复用的指令模板（所有工具都支持）
  • Agents：自定义 AI 代理定义（仅 Claude Code、OpenCode）

两者都以类似方式同步，但 Agents 工具支持有限。

我可以同步 Cursor Rules 吗？

Cursor Rules（.cursorrules 文件）目前不支持。vsync 专注于：

  • Skills
  • MCP 服务器
  • Agents
  • Commands

未来版本可能会根据需求添加 Rules 支持。

故障排除

”找不到配置文件” 错误

解决方案：运行 vsync init 创建配置。

vsync init

“权限被拒绝” 错误

原因：

  • 目标目录没有写权限
  • 符号链接需要管理员权限（在某些系统上）

解决方案：

  1. 检查目录权限：ls -la ~/.cursor/
  2. 在 Windows 上，以管理员身份运行以使用符号链接
  3. 使用复制模式代替："use_symlinks_for_skills": false

Init 期间 “未检测到工具”

原因：工具的配置目录不存在。

解决方案：先创建目录：

mkdir -p ~/.cursor
vsync init

同步挂起或超时

可能原因：

  • 包含许多文件的大型 Skills
  • 网络问题（如果从远程目录读取）
  • 文件系统性能

解决方案：

  1. 使用 --dry-run 测试而不写入
  2. 检查系统资源
  3. 尝试同步更少的项

格式转换问题

症状：同步的配置在目标工具中不工作。

常见问题：

  1. 环境变量未在目标环境中设置
  2. 命令路径在系统之间不同
  3. OpenCode 缺少必需的 type 字段

解决方案：手动验证生成的配置：

# 检查写入了什么
cat .cursor/mcp.json
cat .opencode/opencode.json
cat .codex/config.toml

迁移问题

如何从手动配置管理迁移？

  1. 选择您最完整的工具作为源
  2. 运行 vsync init 并选择该工具
  3. 运行 vsync sync 填充目标
  4. 验证目标工具中的配置
  5. 今后开始只在源工具中编辑

我可以在项目之间迁移吗？

可以，使用 import 命令：

cd new-project
vsync import ../old-project

这会将配置从旧项目复制到您的源工具，然后您可以同步到目标。

从其他同步工具迁移呢？

vsync 不直接从其他同步工具导入，但您可以：

  1. 手动将配置复制到支持的工具之一
  2. 使用该工具作为源
  3. 初始化 vsync
  4. 同步到其他工具

性能问题

vsync 有多快？

典型同步时间：

  • 首次同步：1-3 秒（复制文件）
  • 增量同步：0.5-1 秒（基于哈希的跳过）
  • 使用符号链接：0.3-0.5 秒（无复制）

性能取决于：

  • 项数
  • 文件大小
  • 磁盘速度
  • 目标工具数量

vsync 缓存什么吗？

是的！manifest（.vsync-cache/manifest.json）充当缓存：

  • 存储所有项的 SHA256 哈希值
  • 启用快速变更检测
  • 允许增量同步

我如何加快同步？

  1. 启用符号链接："use_symlinks_for_skills": true
  2. 提交 manifest：在 git 中包含 .vsync-cache/
  3. 使用选择性同步：只同步您需要的
  4. 使用 —yes 标志：跳过确认提示

还有问题？

  • GitHub Issues：提问 
  • 文档：浏览其他文档部分
  • CLI 帮助：运行 vsync --help
Last updated on
高级功能贡献指南