code-server npm 安装完全指南：各平台原生依赖、Node 24 要求与故障排查
本文聚焦 docs/npm.md 所讲解的主题：通过 npm 全局安装 code-server 前，为什么必须为 VS Code 的原生模块预装构建依赖、六大操作系统各自需要哪些软件包、安装后服务如何启动与验证，以及升级 Node.js 版本后原生模块编译失败的排查手段。读完后，你可以在 Ubuntu/Debian、Fedora/CentOS/RHEL、Alpine、macOS、FreeBSD 和 Windows 上独立完成 code-server 的 npm 安装，并具备处理编译与升级问题的实操能力。
为什么 npm 安装需要额外依赖
code-server 的本质是把 VS Code 运行在远程服务器上（见 package.json 中的描述 Run VS Code on a remote server.）。VS Code 内部依赖若干以 C++ 编写的原生 Node 模块（如文件监听、native watcher 等），这些模块在安装时需要按你的操作系统现场编译。因此，通过 npm 安装 code-server 前，必须先安装对应平台的编译工具链与开发库，否则安装过程会在 native module 编译阶段失败。
警告：不要使用 yarn 安装
原文档给出的第一条硬性警告是：不要用 yarn 安装 code-server。与 npm 不同，yarn 对于已分发的应用包不会尊重 lockfile，而是取安装时刻可用的最新版本——这可能与某个 code-server release 实际使用的依赖版本不一致，导致不可预期的行为（原文档引用了项目 issue #4927 作为例证）。
这一警告在仓库中有源码级印证：ci/dev/preinstall.js 在每次 npm install 触发 preinstall 钩子时检查执行环境，一旦发现是 yarn 就直接抛出异常：
if (process.env.npm_execpath.includes("yarn")) {
throw new Error("`yarn` is no longer supported; please use `npm install` instead")
}
也就是说，yarn 路径不仅不推荐，而且会被安装脚本主动拦截。
Node.js 版本要求：24.x
code-server 使用 Node.js 24.x 作为其运行与构建环境，VS Code 官方也有自己的 Node.js 版本要求。使用其他版本的 Node.js 可能引发不可预期行为（原文档引用了 issue #1633 作为例证）。
仓库中有两处直接证据：
-
package.json 中
engines字段声明了硬约束，@types/node也锁定在 24.x："engines": { "node": "24" } -
原生构建的验证脚本 ci/dev/test-native.sh 的注释明确说明了其目的：
# This is to make sure we don't have Node version errors or any other # compilation-related errors.即官方在 CI 中专门用
test:integration验证发行版二进制没有 Node 版本错误或编译相关错误，可见 Node 版本与原生模块的耦合度之高。
实操建议：安装前用 node -v 确认版本为 24.x。若系统 Node 版本过低，请先升级 Node 本身，再执行下文各平台依赖安装。
各操作系统的依赖安装
以下为原文档按操作系统给出的完整依赖安装命令，请根据你的系统选择对应小节执行。
Ubuntu, Debian
sudo apt-get install -y \
build-essential \
pkg-config \
python3
npm config set python python3
build-essential 提供 gcc/g++ 等编译工具链，pkg-config 供原生模块探测系统库，python3 用于 node-gyp 等构建脚本；最后一条命令让 npm 明确使用 python3 解释器。
Fedora, CentOS, RHEL
sudo yum groupinstall -y 'Development Tools'
sudo yum config-manager --set-enabled PowerTools # unnecessary on CentOS 7
sudo yum install -y python2
npm config set python python2
注意此平台与 Debian 系不同，构建脚本默认依赖 python2，因此单独安装并用 npm config set python python2 指定解释器。
Alpine
apk add alpine-sdk bash libstdc++ libc6-compat python3 krb5-dev
alpine-sdk 提供 musl 环境下的全套编译工具链，libc6-compat 提供 glibc 兼容层，krb5-dev 提供 Kerberos 开发头文件（部分原生模块编译所需）。Alpine 基于 musl libc 而非 glibc，这也是 ci/lib.sh 中 os() 函数专门用 ldd --version 输出里的 musl 字样识别 Alpine 的原因。
macOS
xcode-select --install
安装 Apple 命令行工具链（Clang 等）即可满足编译需求。
FreeBSD
pkg install -y git python npm-node24 pkgconf
pkg install -y libinotify
其中 npm-node24 包保证了 Node 24 环境，libinotify 提供文件变化监听的 C 库支持（对应 VS Code 的 native watcher 模块）。
Windows
Windows 上安装 code-server 需要 VS Code 开发所需的全部先决条件；安装 C++ 编译工具链时，原文档推荐使用 "Option 2: Visual Studio 2019" 以获得最佳效果。
随后按 Installing 一节执行：
npm install --global code-server
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
Windows 特有的两个注意点：
-
postinstall 脚本与默认 shell：
postinstall.sh会尝试运行，你需要把终端（例如 Git bash）设为 npm run-scripts 的默认 shell。如果没弹出选择对话框，重新执行一次安装命令。postinstall 的具体行为见下文 postinstall 脚本做了什么。 -
code-server命令找不到：需要把全局 npm 前缀目录加入 PATH。用以下命令定位该目录：npm config get prefix
安装
完成对应操作系统的依赖安装后，全局安装 code-server 包并启动：
npm install --global code-server
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
启动后访问 http://127.0.0.1:8080，初始密码存放在 ~/.config/code-server/config.yaml 中。这一默认行为在源码中可以得到印证：
npm install --global code-server安装的是 package.json 中声明的bin入口："code-server": "out/node/entry.js"，即 src/node/entry.ts 编译后的产物。该入口负责解析命令行参数（parse）、读取配置文件（readConfigFile）、填充默认值（setDefaults），然后启动服务进程或把 VS Code 风格参数转交给 CLI 子进程。- 默认监听地址与配置路径来自 src/node/cli.ts：默认配置模板为
bind-addr: 127.0.0.1:8080（约 L724），而配置文件路径由path.join(paths.config, "config.yaml")拼出（约 L744），即 XDG 配置目录下的config.yaml（通常为~/.config/code-server/config.yaml）。因此--bind-addr参数可以覆盖默认监听地址与端口。
排查问题
若仍需更多帮助，原文档建议到项目官方的 GitHub Discussions 页面发帖（此处不提供外链）。以下两个小节是文档给出的具体排障手段。
升级 Node.js 版本后的模块问题
如果你用 npm 安装了 code-server，之后又升级了 Node.js 版本，则可能需要重新安装 code-server 以重编译原生模块——因为已编译的二进制与当前 Node ABI 不再匹配。一个更快的替代方案：进入 code-server 的 lib/vscode 目录执行 npm rebuild 重新编译模块。
原文档给出的分步示例（以 Homebrew 安装为例）：
- 安装 code-server：
brew install code-server - 进入其 lib/vscode 目录：
cd /usr/local/Cellar/code-server/<version>/libexec/lib/vscode/ - 重编译原生模块：
npm rebuild - 重启 code-server
lib/vscode 正是 VS Code 源码所在的 git submodule（仓库根目录下的 lib/vscode 目录）。值得注意的是，ci/dev/postinstall.sh 在安装前会检查该子模块的 package.json 是否存在，缺失时会明确提示：
if [[ ! -f "$1/package.json" ]]; then
echo "$1/package.json is missing; did you run git submodule update --init?"
exit 1
fi
也就是说，若在克隆仓库的场景下 lib/vscode 为空，需先执行 git submodule update --init 再继续安装。
postinstall 脚本做了什么
npm install 全局安装 code-server 时会触发 package.json 中的 "postinstall": "./ci/dev/postinstall.sh"。从 ci/dev/postinstall.sh 可以看到它依次对三个目录执行 npm ci（CI 环境）或 npm install：
test/—— 测试工具链；test/e2e/extensions/test-extension/—— e2e 测试扩展；lib/vscode/—— VS Code 本体及其原生模块依赖（可用环境变量SKIP_SUBMODULE_DEPS跳过）。
这正是 Windows 一节中提醒"选择 npm run-scripts 默认 shell"的原因：postinstall 是一个 bash 脚本，需要可用的 bash 环境（Windows 下即 Git bash）。
用 npm 详细日志调试安装问题
当安装过程本身失败时，先卸载再用 verbose 日志重装，定位卡在哪一步：
# Uninstall
npm uninstall --global code-server > /dev/null 2>&1
# Install with logging
npm install --loglevel verbose --global code-server
重点观察日志中 node-gyp / 原生模块编译阶段的输出，通常缺失的依赖（编译器、python、pkg-config 头文件）会直接体现在报错里。
附注：哪些平台实际上走 npm 安装
code-server 的官方一键安装脚本（install.sh）对不同发行版有 deb/rpm/AUR/Homebrew/standalone 等优先路径，但当没有对应发行版包或架构不受支持时会回落到 npm 路径。test/scripts/install.bats 中的测试用例清晰地展示了这一点：
- Alpine 与 FreeBSD 的所有架构均固定走
npm（should-use-npm）； - Debian/Fedora 的 i386 架构无独立发行包，回落到
npm（Falling back to installation from npm）； - macOS 无 Homebrew 且架构不受支持时，同样最终回落到
npm。
因此，本文档中各平台的 npm 安装流程不仅是"可选方案"，对 Alpine、FreeBSD 以及 32 位架构而言就是唯一方案，这也是完整理解原文档各平台依赖清单背景的价值所在。
小结
- npm 安装 code-server 的前置条件是各平台的 C++ 编译工具链 + Python + pkg-config（Linux 系）或 Xcode CLT（macOS）/ VS 工具链（Windows）；
- 必须使用 Node.js 24.x（
engines.node = "24"），且严禁使用 yarn（preinstall 钩子会主动拦截）; - 安装后默认监听
127.0.0.1:8080，密码在~/.config/code-server/config.yaml； - 升级 Node 后原生模块异常时，用
npm rebuild（在lib/vscode下）或整体重装解决； - 安装失败时用
npm install --loglevel verbose获取详细日志定位编译错误。
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0627
Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。Python00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比，它在复杂编程和长程任务上的表现显著提升。Jinja00- GLM-5.3-FlashGLM-5.3-Flash (320B-A18B)，是GLM-5系列的首个原生多模态模型。320B总参数，能力超过GLM-5.2Jinja00
Spark-X2.5-4BSpark-X2.5-4B 旨在让强大的 AI 更实用、更高效、更易获得。在广泛日常任务中表现强劲，涵盖对话、写作、翻译、推理、编码、工具调用以及智能体工作流，并在同等规模的开源模型中取得领先成绩。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00- Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色，涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流，并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00
项目优选
kernel
ops-transformer
pytorch
docs
kernelops-nn
jiuwenswarmops-mathcann-learning-hubAscendNPU-IR