设置同步

设置同步允许您在多台机器上共享 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 帐户登录。未来可能会支持其他身份验证提供程序，您可以在问题 #88309 中查看提议的身份验证提供程序 API。

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

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

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

密钥链问题排查

注意：本节适用于 VS Code 版本 1.80 及更高版本。在 1.80 中，我们放弃了 keytar（因为它已被存档），转而使用 Electron 的 safeStorage API。

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

设置同步使用操作系统密钥链进行加密，以在桌面上持久化身份验证信息。如果密钥链配置错误或环境未被识别，使用密钥链有时会失败。

为了帮助诊断问题，您可以使用以下标志重启 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 模块来发现和存储密钥环中的加密密钥信息。Chromium 支持多种不同的桌面环境。下面列出了一些流行的桌面环境和故障排除步骤，如果密钥环配置错误，这些步骤可能会有所帮助。

GNOME 或 UNITY（或类似环境）

如果您看到的错误是“无法在锁定集合中创建项”，则很可能是您的密钥环的“Login”密钥环被锁定。您应该启动操作系统的密钥环（Seahorse 是常用的密钥环 GUI），并确保默认密钥环（通常称为“Login”密钥环）已解锁。此密钥环需要在您登录系统时解锁。

KDE

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

您的钱包（即密钥环）可能已关闭。如果您打开KWalletManager，您可以查看默认的kdewallet是否已关闭，如果是，请确保将其打开。

如果您正在使用 KDE5 或更高版本，并且在连接到 kwallet5 时遇到问题（例如问题 #189672 中非官方 VS Code Flatpak 的用户），您可以尝试将密钥环配置为 gnome-libsecret，因为这将使用 Secret Service API 与任何有效密钥环进行通信。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 的密钥环

您可以手动告诉 VS Code 使用哪个密钥环，方法是传递 password-store 标志。我们推荐的配置是，如果您还没有安装 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 的密钥环，以下是 password-store 的所有可能值：

• kwallet5：用于kwalletmanager5。
• gnome-libsecret：用于任何实现Secret Service API的软件包（例如gnome-keyring、kwallet5、KeepassXC）。
• （不推荐） kwallet：用于旧版 kwallet。
• （不推荐） basic：有关更多详细信息，请参阅下面的基本文本部分。

如果您遇到任何问题，请随时在 VS Code 上提出问题，并附上详细日志。

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

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

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

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

是的。请参阅同步稳定版与预览版一节了解更多信息。

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