使用文档

快速开始

VSCodium 的使用体验与 VS Code 完全一致，如果您之前使用过 VS Code，可以零成本切换。本章节将带您在几分钟内完成安装并开始编码。

VSCodium 是基于 Visual Studio Code 开源源代码构建的社区版本，保留了 VS Code 的全部核心功能，包括 IntelliSense 智能补全、内置调试器、Git 集成、终端等。与 VS Code 的区别在于：VSCodium 移除了微软的遥测追踪、品牌标识和专有许可，采用完全开放的 MIT 许可证发布，让您的代码编辑体验更加纯净、安全、自由。

无论您是个人开发者、企业团队还是教育机构，VSCodium 都能提供与 VS Code 一致的工作流，同时在隐私和许可方面给予您更大的保障。接下来让我们开始安装。

安装指南

VSCodium 支持多种安装方式，您可以选择最适合自己场景的方法。对于大多数用户，推荐使用操作系统的包管理器进行安装，这样可以方便地获取后续更新。

方式一：使用包管理器安装（推荐）

包管理器安装是最便捷的方式，可自动处理依赖和后续更新。以下是各平台推荐的安装命令：

Windows 平台

Windows 用户可以使用 WinGet（Windows 10 1809 及以上版本内置）进行安装：

也可以使用 Chocolatey 或 Scoop：

macOS 平台

macOS 用户推荐使用 Homebrew 安装：

Linux 平台

Linux 各发行版均有原生支持。Debian/Ubuntu 用户可通过 deb 仓库安装：

Fedora/RHEL 用户：

Arch Linux 用户可通过 AUR 安装：

通用发行版可使用 Snap 或 Flatpak：

方式二：下载安装包

如果不使用包管理器，可直接从 下载中心 或 GitHub Releases 下载对应平台的安装包。Windows 提供 .exe 安装包和便携版 .zip，macOS 提供 .dmg 和 .zip，Linux 提供 .deb、.rpm、AppImage 等多种格式。

首次启动

安装完成后，从开始菜单（Windows）、启动台（macOS）或应用菜单（Linux）启动 VSCodium。首次启动会自动创建用户配置目录，整个过程无需任何额外配置。

VSCodium 的界面布局与 VS Code 完全一致：左侧是活动栏（包含资源管理器、搜索、源代码管理、运行调试、扩展等图标），中间是编辑区，底部是状态栏和面板区域。如果您之前使用过 VS Code，会感到非常熟悉。

macOS 首次启动提示

macOS Mojave 及部分版本用户首次打开时可能提示"App can't be opened because Apple cannot check it for malicious software"。这是由于 VSCodium 使用了社区开发者证书签名。解决方法：

• 在 Finder 中找到 VSCodium 应用
• 右键点击应用图标，选择"打开"
• 在弹出的对话框中点击"打开"确认
• 此后即可正常双击打开，仅首次需要此操作

基础配置

VSCodium 的所有设置都通过 JSON 配置文件管理。可通过 Ctrl+,（Windows/Linux）或 Cmd+,（macOS）打开设置界面，也可直接编辑 settings.json 文件进行高级配置。

配置文件位于用户数据目录下。各平台路径如下：

• Windows：%APPDATA%\VSCodium\User\settings.json
• macOS：~/Library/Application Support/VSCodium/User/settings.json
• Linux：~/.config/VSCodium/User/settings.json

推荐的隐私配置

VSCodium 默认已关闭所有遥测，但您可进一步检查或自定义以下设置：

{
    "telemetry.telemetryLevel": "off",
    "telemetry.enableTelemetry": false,
    "telemetry.enableCrashReporter": false,
    "telemetry.editStats.enabled": false,
    "workbench.enableExperiments": false,
    "workbench.settings.enableNaturalLanguageSearch": false,
    "chat.disableAIFeatures": true,
    "update.mode": "default"
}

切换扩展市场

默认情况下，VSCodium 使用 Open VSX Registry 作为扩展市场。如需切换到自托管或其他扩展仓库，可在 product.json 中修改 extensionsGallery 配置：

// 路径：安装目录/resources/app/product.json
"extensionsGallery": {
    "serviceUrl": "https://your-registry.example.com/api",
    "itemUrl": "https://your-registry.example.com/item"
}

扩展安装

VSCodium 通过 Open VSX Registry 获取扩展。点击左侧活动栏的扩展图标，或按 Ctrl+Shift+X（Windows/Linux）/ Cmd+Shift+X（macOS）打开扩展面板，即可搜索和安装扩展。

Open VSX 托管了超过 10,000 个扩展，覆盖主流编程语言和开发场景。大部分开源扩展（主题、Linters、语言服务器、代码片段等）均可直接安装使用。少数微软专有扩展（如 C/C++、Python 官方版、Remote 系列）需要使用开源替代方案。

推荐的开源替代扩展

以下是常用微软专有扩展的开源替代方案，功能上可满足绝大多数开发需求：

• C/C++ 开发：使用 clangd（LLVM）替代 ms-vscode.cpptools，提供基于 Clang 的智能补全和错误诊断
• C/C++ 调试：使用 Native Debug 替代，支持 GDB 和 LLDB 调试器
• Python 开发：使用 BasedPyright 替代 ms-python.python，提供强大的类型检查和智能补全
• 远程 SSH：使用 Open Remote - SSH 替代，需在 SSH 配置中启用 AllowTcpForwarding yes
• WSL 开发：使用 Open Remote - WSL 替代，功能与官方版本基本一致

手动安装 VSIX 扩展

如果某些扩展未上架 Open VSX，可从其他来源获取 .vsix 文件手动安装：

• 在扩展面板点击右上角的"..."菜单
• 选择"从 VSIX 安装"
• 选择本地 .vsix 文件即可完成安装

也可通过命令行安装：

启用 GitHub Copilot（可选）

默认情况下 VSCodium 禁用 AI 功能。如需启用 GitHub Copilot，需手动配置。请注意这会向 GitHub 服务器发送代码上下文：

// 在 settings.json 中添加
"chat.disableAIFeatures": false,
"github.copilot.advanced": {
    "debug.overrideProxyUrl": "https://copilot-proxy.githubusercontent.com"
}

然后从 VSIX 手动安装 Copilot 扩展。我们也推荐尝试 Codeium、Continue.dev、Tabby 等开源 AI 编程助手。

从 VS Code 迁移

VSCodium 与 VS Code 使用完全独立的配置和扩展目录，两者可并存安装。迁移过程本质上是将 VS Code 的配置复制到 VSCodium 对应目录。

配置目录对照

各平台配置目录对应关系如下：

迁移步骤

建议按以下步骤进行迁移，避免一次性整盘复制带来的兼容性问题：

1. 盘点扩展：列出当前在 VS Code 中使用的扩展，分类为"Open VSX 可用 / 需 VSIX 安装 / 需找替代 / 受限不可用"四类
2. 复制配置文件：将 settings.json 和 keybindings.json 从 VS Code 目录复制到 VSCodium 对应目录
3. 复制代码片段：如果使用了自定义 Snippets，将 snippets 目录一并复制
4. 安装扩展：在 VSCodium 扩展面板搜索并安装所需扩展，优先安装 Open VSX 上可用的
5. 验证测试：打开常用项目，验证关键功能是否正常工作

命令行别名

VSCodium 的命令行工具名为 codium（而非 code）。如果您习惯使用 code 命令，可设置别名：

Windows 用户可在 PowerShell 配置文件中添加：

高级用法

便携模式

VSCodium 支持便携模式，所有配置和数据存储在程序所在目录的 data 文件夹中，适合从 U 盘运行或在受限环境中使用：

• 下载便携版（Windows 为 .zip，macOS/Linux 为 .tar.gz）
• 解压到任意目录
• 在程序同级目录创建名为 data 的文件夹
• 启动 VSCodium，所有数据将存储在 data 文件夹中

多版本共存

可同时安装稳定版和 Insiders 预览版，两者使用不同的配置目录，互不干扰。Insiders 版本适合参与测试、提前体验新功能，但不建议用于生产环境。

命令行参数

VSCodium 支持丰富的命令行参数，常用示例如下：

自托管扩展仓库

企业用户可部署自己的 Open VSX 实例，实现扩展的内部审核和分发。Open VSX 是开源项目，可参考 官方文档 进行部署。部署完成后，修改 VSCodium 的 product.json 中的 extensionsGallery 配置指向自托管实例即可。

常见问题

以下收集了用户最常问的问题。如果这里没有您需要的答案，可前往 GitHub Issues 提问或搜索已有讨论。