设置同步
设置同步允许您在不同设备之间共享 Visual Studio Code 配置,例如设置、键盘快捷方式和已安装的扩展,从而让您始终使用您喜欢的设置。
注意:VS Code 不会将您的扩展同步到远程窗口或从远程窗口同步,例如当您连接到 SSH、开发容器 (devcontainer) 或 WSL 时。
开启设置同步
您可以通过使用管理齿轮菜单中的备份和同步设置...条目或活动栏底部的帐户菜单来开启设置同步。
要使用同步设置,您需要登录并选择要同步的设置。目前,设置同步支持以下设置
- 设置
- 键盘快捷方式
- 用户代码片段
- 用户任务
- UI 状态
- 扩展
- 配置文件
当您选择登录按钮时,您可以选择使用您的 Microsoft 帐户或 GitHub 帐户登录。
做出选择后,浏览器会打开,以便您可以登录您的 Microsoft 或 GitHub 帐户。如果您选择 Microsoft 帐户,您可以使用个人帐户(例如 Outlook 帐户)或 Azure 帐户,并且您还可以将 GitHub 帐户链接到新的或现有的 Microsoft 帐户。
登录后,设置同步将开启,并继续在后台自动同步您的偏好设置。
合并或替换
如果您已经从一台设备同步,并在另一台设备上开启同步,您将看到以下合并或替换对话框。
- 合并:选择此选项会将本地设置与云端的远程设置合并。
- 替换本地:选择此选项将使用云端的远程设置覆盖本地设置。
- 手动合并...:选择此选项将打开合并视图,您可以在其中逐个合并偏好设置。
配置同步数据
机器设置(具有 machine
或 machine-overridable
范围)默认不会同步,因为它们的值特定于给定设备。您也可以从设置编辑器中或使用设置 settingsSync.ignoredSettings 将要同步或不同步的设置添加到此列表或从此列表移除。
键盘快捷方式默认按平台同步。如果您的键盘快捷方式与平台无关,您可以通过禁用设置 settingsSync.keybindingsPerPlatform 来跨平台同步它们。
所有内置和已安装的扩展及其全局启用状态都会同步。您可以跳过同步某个扩展,可以从扩展视图 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 或使用设置 settingsSync.ignoredExtensions。
目前同步的 UI 状态如下
- 显示语言
- 活动栏条目
- 面板条目
- 视图布局和可见性
- 最近使用的命令
- 不再显示通知
您始终可以通过设置同步:配置命令或打开管理齿轮菜单,选择设置同步已开启,然后选择设置同步:配置来更改同步的内容。
冲突
在多台设备之间同步设置时,偶尔可能会发生冲突。冲突可能在首次设置设备之间的同步时发生,或者在设备离线时设置发生更改时发生。发生冲突时,您将看到以下选项
- 接受本地:选择此选项将用您的本地设置覆盖云端的远程设置。
- 接受远程:选择此选项将使用云端的远程设置覆盖本地设置。
- 显示冲突:选择此选项将显示一个类似于源代码管理差异编辑器的差异编辑器,您可以在其中预览本地和远程设置,并选择接受本地或远程,或者手动解决本地设置文件中的更改,然后接受本地文件。
切换帐户
如果您随时想将数据同步到不同的帐户,您可以关闭设置同步,然后使用不同的帐户再次开启。
Stable 版本与 Insiders 版本同步
默认情况下,VS Code Stable 版本和 Insiders 版本使用不同的设置同步服务,因此不共享设置。您可以在开启设置同步时选择 Stable 同步服务来将 Insiders 版本与 Stable 版本同步。此选项仅在 VS Code Insiders 中可用。
注意:由于 Insiders 版本比 Stable 版本新,同步它们有时可能导致数据不兼容。在这种情况下,设置同步将在 Stable 版本上自动禁用,以防止数据不一致。一旦发布了新的 Stable 版本,您可以升级您的 Stable 客户端并开启同步以继续同步。
恢复数据
VS Code 始终在同步时存储您偏好设置的本地和远程备份,并提供视图来访问这些备份。如果出现问题,您可以从这些视图恢复您的数据。
您可以使用命令面板中的设置同步:显示已同步数据命令打开这些视图。本地同步活动视图默认处于隐藏状态,您可以使用设置同步视图溢出操作下的视图子菜单启用它。
您可以通过设置同步:打开本地备份文件夹命令访问磁盘上的本地备份文件夹。该文件夹按偏好设置类型组织,包含您的 JSON 文件的不同版本,文件名以备份时的时间戳命名。
注意:本地备份会在 30 天后自动删除。对于远程备份,每个单独资源(设置、扩展等)的最新 20 个版本会保留。
已同步设备
VS Code 会跟踪同步您偏好设置的设备,并提供一个视图来访问它们。每台设备都会根据 VS Code 的类型(Insiders 或 Stable)及其所在的平台获得一个默认名称。您始终可以使用视图中设备条目上可用的编辑操作来更新设备名称。您还可以使用视图中设备条目上的关闭设置同步上下文菜单操作来禁用另一台设备上的同步。
您可以使用命令面板中的设置同步:显示已同步数据命令打开此视图。
扩展作者
如果您是扩展作者,您应该确保您的扩展在用户启用设置同步时表现适当。例如,您可能不希望您的扩展在多台设备上显示相同的已关闭通知或欢迎页面。
在设备之间同步用户全局状态
如果您的扩展需要在不同设备之间保留一些用户状态,则可以使用 vscode.ExtensionContext.globalState.setKeysForSync
将状态提供给设置同步。在设备之间共享 UI 关闭或查看标记等状态可以提供更好的用户体验。
在扩展功能主题中有一个使用 setKeysforSync
的示例。
报告问题
设置同步活动可以在输出 (设置同步) 视图中监控。如果您遇到设置同步问题,请在创建问题时包含此日志。如果您的问题与身份验证相关,也请包含帐户输出视图中的日志。
如何删除我的数据?
如果您想从我们的服务器中删除所有数据,只需通过管理齿轮菜单下的设置同步已开启菜单关闭同步,并选中清除所有云数据的复选框即可。如果您选择重新启用同步,就好像您是第一次登录一样。
后续步骤
- 用户和工作区设置 - 了解如何通过用户和工作区设置根据您的偏好配置 VS Code。
常见问题
VS Code 设置同步与 Settings Sync 扩展是同一个东西吗?
不,由 Shan Khan 开发的 Settings Sync 扩展使用 GitHub 上的私有 Gist 在不同设备之间共享您的 VS Code 设置,与 VS Code 的设置同步无关。
我可以使用哪种类型的帐户进行设置同步登录?
VS Code 设置同步支持使用 Microsoft 帐户(例如 Outlook 或 Azure 帐户)或 GitHub 帐户登录。不支持使用 GitHub Enterprise 帐户登录。未来可能会支持其他身份验证提供程序,您可以在 问题 #88309 中查看提议的身份验证提供程序 API。
注意:目前 VS Code 设置同步不支持使用您的 Microsoft 主权云帐户。如果您希望支持,请在此 GitHub 问题中告知我们您想使用哪种 Microsoft 主权云。
我可以使用不同的后端或服务进行设置同步吗?
设置同步使用专用服务来存储设置和协调更新。未来可能会公开服务提供程序 API,以允许自定义设置同步后端。
故障排除 keychain 问题
注意:本节适用于 VS Code 版本 1.80 及更高版本。在 1.80 中,我们放弃了 keytar(由于其已归档),转而使用 Electron 的 safeStorage API。
注意:在本文档中,keychain、keyring、wallet、credential store 都是同义词。
设置同步在桌面上使用操作系统 keychain 进行加密来持久化身份验证信息。如果 keychain 配置错误或环境无法识别,使用 keychain 在某些情况下可能会失败。
为了帮助诊断问题,您可以带以下标志重新启动 VS Code 以生成详细日志
code --verbose --vmodule="*/components/os_crypt/*=1"
Windows 和 macOS
目前,Windows 或 macOS 上没有已知的配置问题,但是,如果您怀疑有问题,您可以在 VS Code 上提出问题,并附上上述详细日志。这对于我们支持其他桌面配置非常重要。
Linux
在上一个命令生成的日志顶部,您将看到类似于以下内容
[9699:0626/093542.027629:VERBOSE1:key_storage_util_linux.cc(54)] Password storage detected desktop environment: GNOME
[9699:0626/093542.027660:VERBOSE1:key_storage_linux.cc(122)] Selected backend for OSCrypt: GNOME_LIBSECRET
我们依靠 Chromium 的 oscrypt 模块来发现并将加密密钥信息存储在 keyring 中。Chromium 支持多种不同的桌面环境。下面列出了一些流行的桌面环境以及在 keyring 配置错误时可能有帮助的故障排除步骤。
GNOME 或 UNITY(或类似环境)
如果您看到的错误是“无法在锁定的集合中创建项”,很可能是您的 keyring 的 Login
keyring 被锁定。您应该启动操作系统的 keyring(Seahorse 是查看 keyring 的常用 GUI),并确保默认 keyring(通常称为 Login
keyring)已解锁。当您登录系统时,此 keyring 需要解锁。
KDE
Visual Studio Code 尚未完全支持 KDE 6。作为一种解决方法:最新的 kwallet6 也可以作为 kwallet5 访问,因此您可以通过将密码存储设置为
kwallet5
来强制其使用 kwallet5,具体方法如下文 配置与 VS Code 一起使用的 keyring 中所述。
您的钱包(即 keyring)可能已关闭。如果您打开 KWalletManager,您可以查看默认的 kdewallet
是否已关闭,如果已关闭,请确保打开它。
如果您正在使用 KDE5 或更高版本,并且连接 kwallet5
时遇到问题(就像问题 #189672 中非官方 VS Code Flatpak 的用户一样),您可以尝试将 keyring 配置为 gnome-libsecret
,因为这将使用 Secret Service API 与任何有效的 keyring 进行通信。kwallet5
实现了 Secret Service API,可以使用此方法访问。
如果您仍然连接 kwallet5
时遇到问题,一些用户报告称授予特定的 D-Bus 服务权限是可行的解决方案
flatpak override --user --talk-name=org.kde.kwalletd5 --talk-name=org.freedesktop.secrets com.visualstudio.code
其他 Linux 桌面环境
首先,如果未检测到您的桌面环境,您可以在 VS Code 上提出问题,并附上上述详细日志。这对于我们支持其他桌面配置非常重要。
(推荐)配置与 VS Code 一起使用的 keyring
您可以通过传递 password-store
标志手动告诉 VS Code 使用哪个 keyring。我们推荐的配置是先安装 gnome-keyring(如果您还没有),然后使用 code --password-store="gnome-libsecret"
启动 VS Code。
如果此解决方案对您有效,您可以通过打开命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 并运行首选项:配置运行时参数命令来保留 password-store
的值。这将打开 argv.json
文件,您可以在其中添加设置 "password-store":"gnome-libsecret"
。
如果您想尝试使用除 gnome-keyring
之外的其他 keyring,以下是 password-store
的所有可能值
kwallet5
:用于 kwalletmanager5。gnome-libsecret
:用于实现 Secret Service API 的任何包(例如gnome-keyring
、kwallet5
、KeepassXC
)。- (不推荐)
kwallet
:用于旧版本kwallet
。 - (不推荐)
basic
:有关更多详细信息,请参阅下面的关于基本文本部分。
如果您遇到任何问题,请随时在 VS Code 上提出问题,并附上详细日志。
(不推荐)配置基本文本加密
我们依靠 Chromium 的 oscrypt 模块来发现并将加密密钥信息存储在 keyring 中。Chromium 提供了一种可选的备用加密策略,该策略使用基于 Chromium 源代码中硬编码字符串的内存密钥。因此,这种备用策略充其量只是混淆,只有在您接受系统上任何进程理论上都可以解密您存储的密钥的风险时才应使用。
如果您接受此风险,您可以通过打开命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 并运行首选项:配置运行时参数命令将 password-store
设置为 basic
。这将打开 argv.json
文件,您可以在其中添加设置 "password-store":"basic"
。
我可以在 VS Code Stable 版本和 Insiders 版本之间共享设置吗?
是的。请参阅Stable 版本与 Insiders 版本同步部分了解更多信息。
请注意,这有时可能导致数据不兼容,因为 Insiders 版本比 Stable 版本新。在这种情况下,设置同步将在 Stable 版本上自动禁用,以防止数据不一致。一旦发布了新的 Stable 版本,您可以升级您的客户端并开启设置同步以继续同步。