设置同步

设置同步可让您跨机器共享 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 状态如下

• 显示语言
• 活动栏条目
• 面板条目
• 视图布局和可见性
• 最近使用的命令
• 不再显示通知

您始终可以通过“设置同步：配置”命令或打开“管理”齿轮菜单，选择“设置同步已开启”，然后选择“设置同步：配置”来更改要同步的内容。

冲突

在多台机器之间同步设置时，偶尔可能会发生冲突。当首次在机器之间设置同步或在机器离线时设置发生更改时，可能会发生冲突。发生冲突时，您将看到以下选项

• 接受本地：选择此选项将用您的本地设置覆盖云端的远程设置。
• 接受远程：选择此选项将用云端的远程设置覆盖本地设置。
• 显示冲突：选择此选项将显示一个类似于源代码管理差异编辑器的差异编辑器，您可以在其中预览本地和远程设置，并选择接受本地或远程设置，或者手动解决本地设置文件中的更改，然后接受本地文件。

切换账户

如果您想随时将数据同步到其他账户，您可以关闭设置同步，然后用另一个账户重新开启设置同步。“设置同步：关闭”命令用于关闭同步。

同步稳定版与预览版

默认情况下，VS Code 稳定版和 预览版 构建使用不同的设置同步服务，因此不共享设置。您可以选择稳定版的同步服务来同步您的预览版设置。此选项仅在 VS Code 预览版中可用。

注意：由于预览版构建比稳定版构建更新，因此同步它们有时会导致数据不兼容。在这种情况下，为防止数据不一致，设置同步将在稳定版上自动禁用。一旦发布了新版本的稳定版构建，您就可以升级您的稳定版客户端并开启同步以继续同步。

恢复数据

VS Code 在同步时始终会存储您偏好设置的本地和远程备份，并提供视图供您访问。万一出现问题，您可以从这些视图中恢复您的数据。

您可以使用命令面板中的“设置同步：显示同步数据”命令打开这些视图。本地同步活动视图默认隐藏，您可以使用“设置同步”视图溢出操作下的“视图”子菜单来启用它。

可以通过“设置同步：打开本地备份文件夹”命令访问磁盘上的本地备份文件夹。文件夹按偏好设置类型组织，并包含您的 JSON 文件的版本，文件名为备份发生的时间戳。

注意：本地备份会在 30 天后自动删除。对于远程备份，将保留每个单独资源（设置、扩展等）的最新 20 个版本。

同步的机器

VS Code 会跟踪同步您偏好设置的机器，并提供一个视图供您访问。每台机器都有一个基于 VS Code 类型（预览版或稳定版）和其所在平台的默认名称。您始终可以通过视图中机器条目上的编辑操作来更新机器名称。您也可以使用视图中机器条目上的“关闭设置同步”上下文菜单操作在另一台机器上禁用同步。

您可以使用命令面板中的“设置同步：显示同步数据”命令打开此视图。

扩展作者

如果您是扩展作者，您应该确保您的扩展在用户启用设置同步时行为得当。例如，您可能不希望您的扩展在多台机器上显示相同的已忽略通知或欢迎页面。

在机器之间同步用户全局状态

如果您的扩展需要在不同机器之间保留某些用户状态，请使用 vscode.ExtensionContext.globalState.setKeysForSync 将状态提供给设置同步。跨机器共享 UI 已忽略或已查看标志等状态可以提供更好的用户体验。

在“扩展功能”主题的 数据存储 中有一个使用 setKeysforSync 的示例。

报告问题

可以在“日志（设置同步）”输出视图中监视设置同步活动。如果您遇到设置同步问题，请在创建问题时包含此日志。如果问题与身份验证有关，也请包含“账户”输出视图中的日志。

如何删除我的数据？

如果您想从我们的服务器中删除所有数据，只需通过“管理”齿轮菜单下的“设置同步已开启”菜单关闭同步，并勾选清除所有云数据复选框。如果您选择重新启用同步，它将如同您第一次登录一样。

后续步骤

• 用户和工作区设置 - 了解如何通过用户和工作区设置将 VS Code 配置为您喜欢的样式。

常见问题

VS Code 设置同步与设置同步扩展相同吗？

不，Shan Khan 的 设置同步扩展使用 GitHub 上的私有 Gist 来在不同机器之间共享您的 VS Code 设置，与 VS Code 设置同步无关。

我可以使用什么类型的账户进行设置同步登录？

VS Code 设置同步支持使用 Microsoft 账户（例如 Outlook 或 Azure 账户）或 GitHub 账户登录。不支持使用 GitHub Enterprise 账户登录。将来可能会支持其他身份验证提供商，您可以在 issue #88309 中查看提议的身份验证提供商 API。

注意：VS Code 设置同步目前不支持使用您的 Microsoft 主权云账户。如果您希望使用此功能，请在 此 GitHub issue 中告知我们您希望使用哪种 Microsoft 主权云。

我可以使用不同的后端或服务进行设置同步吗？

设置同步使用专用服务来存储设置和协调更新。将来可能会公开服务提供商 API，以允许自定义设置同步后端。

故障排除密钥链问题

注意：本节适用于 VS Code 版本1.80 及更高版本。在 1.80 版本中，由于 keytar 已归档，我们已弃用它，而转向使用 Electron 的 safeStorage API。

注意：keychain、keyring、wallet、credential store 在本文档中是同义词。

设置同步在桌面平台上使用 OS keychain 进行加密来持久化身份验证信息。在某些情况下，如果 keychain 配置不正确或环境未被识别，使用 keychain 可能会失败。

为了帮助诊断问题，您可以使用以下标志重启 VS Code 来生成详细日志

code --verbose --vmodule="*/components/os_crypt/*=1"

Windows 和 macOS

目前，Windows 或 macOS 上没有已知的配置问题，但是，如果您怀疑有问题，可以向 VS Code 提交 issue 并附上上述详细日志。这对我们支持其他桌面配置非常重要。

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（或类似环境）

如果您看到的错误是“Cannot create an item in a locked collection”，那么很可能是您的 keyring 的 Login keyring 被锁定了。您应该启动您的 OS 的 keyring（Seahorse 是常用的查看 keyring 的 GUI）并确保默认 keyring（通常称为 Login keyring）已解锁。在您登录系统时需要解锁此 keyring。

KDE

Visual Studio Code 尚未完全支持 KDE 6。作为一种变通方法：最新的 kwallet6 也可以作为 kwallet5 访问，因此您可以强制它使用 kwallet5，方法如下面 配置 keyring 以便与 VS Code 配合使用 中所述，将密码存储设置为 kwallet5。

您的钱包（也称为 keyring）可能已关闭。如果您打开 KWalletManager，您可以看到默认的 kdewallet 是否已关闭，如果已关闭，请确保将其打开。

如果您正在使用 KDE5 或更高版本，并且在连接到 kwallet5 时遇到问题（例如，非官方 VS Code Flatpak 在 issue #189672 中遇到的问题），您可以尝试 将 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 提交 issue 并附上上述详细日志。这对我们支持其他桌面配置非常重要。

（推荐）配置 keyring 以便与 VS Code 配合使用

您可以通过传递 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：有关更多详细信息，请参阅下面关于基本文本加密的部分。

如果您的密码存储未自动检测到，请查看 issue #187338 中是否提到了您的设置。如果没有，请随时在此处包含您的设置，或者如果您认为问题与自动密码存储检测无关，请向 VS Code 提交 issue 并附上详细日志。

（不推荐）配置基本文本加密

我们依赖 Chromium 的 oscrypt 模块来发现和存储加密密钥信息在 keyring 中。Chromium 提供了一个选择加入的回退加密策略，该策略使用基于 Chromium 源代码中硬编码字符串的内存中密钥。因此，这种回退策略充其量只是一种混淆，只有在您接受任何系统进程理论上都可以解密您存储的秘密的风险时才应使用。

如果您接受此风险，可以通过打开命令面板（⇧⌘P (Windows、Linux Ctrl+Shift+P)）并运行“首选项：配置运行时参数”命令将 password-store 设置为 basic。这将打开 argv.json 文件，您可以在其中添加设置 "password-store":"basic"。

我可以在 VS Code 稳定版和预览版之间共享设置吗？

是的。有关更多信息，请参阅同步稳定版与预览版部分。

请注意，这有时会导致数据不兼容，因为预览版构建比稳定版构建更新。在这种情况下，为防止数据不一致，设置同步将在稳定版上自动禁用。一旦发布了新版本的稳定版构建，您就可以升级您的客户端并开启设置同步以继续同步。