code-server 安装完全指南：从 install.sh 自动检测到各平台部署与源码级原理

code-server 是一款运行在远程服务器上的 VS Code，通过浏览器访问完整的 IDE 体验。本文基于官方安装文档 docs/install.md 完整梳理所有受支持的安装途径——install.sh 自动检测脚本、npm、Standalone 独立发行版、Debian/Ubuntu、Fedora/RHEL、Arch、macOS、Docker、Helm 等——并结合仓库内的 install.sh 脚本源码、package.json 入口配置与 测试脚本 深入讲解检测逻辑、版本解析与缓存机制，帮助你在任意 Linux 发行版、macOS 或容器环境下一键部署并验证 code-server。

一、install.sh：官方推荐的自动安装方式

安装 code-server 最简单的方式是使用官方安装脚本，它适用于 Linux、macOS 和 FreeBSD，并会优先尝试使用系统包管理器。可以先用 --dry-run 预览安装过程：

curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run

正式安装执行：

curl -fsSL https://code-server.dev/install.sh | sh

1.1 可用的安装参数

文档列出的核心参数如下：

参数	作用
--dry-run	只打印将要执行的命令，不实际运行
--method=detect	检测系统包管理器，失败时回退到 --method=standalone
--method=standalone	将 Standalone 发行版归档安装到 ~/.local
--prefix=/usr/local	将 Standalone 归档系统级安装（默认 ~/.local）
--version=X.X.X	安装指定版本而非最新版
--edge	安装最新的 edge（预发布）版本
--help	查看使用说明

从 install.sh 源码的 usage() 函数（L7-L74）还可以看到文档未逐条展开的两个实用能力：

• --rsh <bin>：指定远程安装使用的 shell，默认 ssh；脚本支持直接传入 user@host 参数，通过 ssh 在远程主机上完成安装（远端需能访问互联网）。
• 所有下载的资产会缓存到 ~/.cache/code-server（源码函数 echo_cache_dir，L579-L587，支持 XDG_CACHE_HOME 覆盖）。

fetch() 函数（L331-L347）还实现了断点续传：下载中的文件先写入 $FILE.incomplete，若目标文件已存在则直接复用缓存。

文档同时提示：若对 curl | sh 的安全性有顾虑，可参考原文档引用的安全分析文章；由于 install.sh 执行的命令与本文档后续各章节展示的命令完全一致，因此也可以对照源码手动审查每一步操作。

1.2 包管理器检测参考（Detection reference）

文档给出的检测规则与脚本 main() 中的分发逻辑（L264-L294）一一对应：

平台	安装方式
Debian、Ubuntu	安装最新 .deb 包
Fedora、CentOS、RHEL、openSUSE	安装最新 .rpm 包
Arch Linux	安装 AUR 包
无法识别的 Linux	安装 Standalone 发行版到 ~/.local（需将 ~/.local/bin 加入 $PATH）
macOS	安装 Homebrew 包；若无 Homebrew 则回退到 Standalone
FreeBSD	使用 npm 安装
没有预编译发行版的架构	使用 npm 安装（npm 包会在 postinstall 阶段编译原生模块）

从源码结构看，检测的具体实现是：

1. os()（L474-L482）将 uname 结果规范化为 linux/macos/freebsd；
2. arch()（L540-L547）将 aarch64 映射为 arm64、x86_64 映射为 amd64——当前官方仅为 amd64 和 arm64 提供预编译发行版；
3. distro()（L496-L519）读取 /etc/os-release，并优先按 ID_LIKE 归类（例如 amzn、centos、rhel 归入 fedora，manjaro、endeavouros 归入 arch）；
4. 各发行版分支通过 npm_fallback 包装器（L451-L459）实现回退：若当前架构没有 Standalone 发行版，则自动改用 npm 安装。Alpine 与 FreeBSD 由于没有对应发行版，直接走 install_npm。

这套检测逻辑由 test/scripts/install.bats 以 --dry-run 方式对各发行版 × 架构组合做了系统化断言，例如 should-use-deb、should-fallback-npm 等辅助函数会精确校验输出的每一步提示文本，保证检测行为在脚本迭代中不回归。

二、npm 安装：适用于特殊环境的构建式安装

以下场景文档建议改用 npm 安装：

1. 机器不是 amd64 或 arm64；
2. Linux 的 glibc < v2.28 或 glibcxx < v3.4.21；
3. 运行 Alpine Linux 或使用非 glibc 的 libc。

npm 方式安装时会在安装阶段构建原生模块，因此需要先准备 C 依赖工具链，详细说明见 docs/npm.md。该文档的关键要点包括：

• Node.js 版本：项目使用 Node.js 24.x（与 package.json 中 engines.node: "24" 一致），使用其他版本可能导致不可预期的行为；
• Ubuntu/Debian：sudo apt-get install -y build-essential pkg-config python3；
• Fedora/CentOS/RHEL：yum groupinstall 'Development Tools' 并安装 python2；
• Alpine：apk add alpine-sdk bash libstdc++ libc6-compat python3 krb5-dev；
• macOS：xcode-select --install；
• FreeBSD：pkg install -y git python npm-node24 pkgconf libinotify；
• 文档明确警告：不要使用 yarn 安装 code-server，因为它不像 npm 那样遵守分发应用的 lockfile。

安装命令：

npm install --global code-server
code-server
# 然后访问 http://127.0.0.1:8080，密码位于 ~/.config/code-server/config.yaml

package.json 中 postinstall 指向 ./ci/dev/postinstall.sh，这就是"构建原生模块"发生的时机；bin 字段将 code-server 命令映射到 out/node/entry.js，即 src/node/entry.ts 编译产物——它解析 CLI 参数与配置文件，随后通过 wrapper 启动服务端。

三、Standalone 独立发行版：自包含的 tar.gz 归档

每个官方版本都会发布自包含的 .tar.gz 归档，归档内捆绑了 node 二进制和 node 模块，且所有其他发行版（deb/rpm/镜像）都是基于 Standalone 版本构建的。

唯一系统要求：Linux 上 glibc >= 2.28 且 glibcxx >= v3.4.21（macOS 无最低版本要求）。

使用步骤：

1. 下载对应系统的最新发行版归档；
2. 解压归档；
3. 执行 ./bin/code-server 运行（可将 ./bin/code-server 加入 $PATH）。

文档提供的 Linux 示例脚本：

mkdir -p ~/.local/lib ~/.local/bin
curl -fL https://github.com/coder/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \
  | tar -C ~/.local/lib -xz
mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION
ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server
PATH="~/.local/bin:$PATH"
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

这段示例与 install.sh 中 install_standalone() 函数（L395-L424）执行的是同一套动作：下载归档 → 解压到 $PREFIX/lib → 重命名去掉架构后缀 → 软链接二进制到 $PREFIX/bin/code-server。源码中还有一个细节：若目标目录已存在同版本安装，脚本会直接退出并提示先删除旧目录。

四、Linux 发行版包管理器安装

4.1 Debian、Ubuntu

注意：Standalone arm64 .deb 不支持 Ubuntu 16.04 及更早版本，请升级系统或改用 npm 构建。

curl -fOL https://github.com/coder/code-server/releases/download/v$VERSION/code-server_${VERSION}_amd64.deb
sudo dpkg -i code-server_${VERSION}_amd64.deb
sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

4.2 Fedora、CentOS、RHEL、SUSE

注意：Standalone arm64 .rpm 不支持 CentOS 7，请升级或改用 npm。

curl -fOL https://github.com/coder/code-server/releases/download/v$VERSION/code-server-$VERSION-amd64.rpm
sudo rpm -i code-server-$VERSION-amd64.rpm
sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

从 install.sh 源码看，deb 安装使用 dpkg -i、rpm 安装使用 rpm -U（L358-L378），两者都要求 root 权限，因此脚本通过 sudo_sh_c（L561-L577）自动选择可用的提权工具：doas、sudo 或 su。

4.3 Arch Linux

使用 yay 或原生 makepkg 从 AUR 安装：

# 方式一：yay
yay -S code-server
sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

# 方式二：makepkg
git clone https://aur.archlinux.org/code-server.git
cd code-server
makepkg -si
sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

4.4 Artix Linux（OpenRC）

Artix 使用 OpenRC 而非 systemd，因此需要手工编写服务脚本：

# 从 AUR 安装
git clone https://aur.archlinux.org/code-server.git
cd code-server
makepkg -si

将下面内容保存为 /etc/init.d/code-server 并执行 chmod +x code-server，把第 3 行替换为你的用户名：

#!/sbin/openrc-run
name=$RC_SVCNAME
description="$name - VS Code on a remote server"
user="" # your username here
homedir="/home/$user"
command="$(which code-server)"
# Just because you can do this does not mean you should. Use ~/.config/code-server/config.yaml instead
#command_args="--extensions-dir $homedir/.local/share/$name/extensions --user-data-dir $homedir/.local/share/$name --disable-telemetry"
command_user="$user:$user"
pidfile="/run/$name/$name.pid"
command_background="yes"
extra_commands="report"

depend() {
  use logger dns
  need net
}

start_pre() {
  checkpath --directory --owner $command_user --mode 0755 /run/$name /var/log/$name
}

start() {
  default_start
  report
}

stop() {
  default_stop
}

status() {
  default_status
  report
}

report() {
  # Report to the user
  einfo "Reading configuration from ~/.config/code-server/config.yaml"
}

注册开机自启并立即启动：

rc-update add code-server default
rc-service code-server start

五、macOS 安装

brew install code-server
brew services start code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml

install.sh 对 macOS 的处理逻辑（L267-L276）：检测到 brew 命令则调用 install_brew；否则打印提示并回退到 Standalone 安装，若当前架构无预编译包再进一步回退到 npm——这与 test/scripts/install.bats 中 should-fallback-npm-brew 用例断言的四层回退提示文本完全对应。

六、Docker 容器部署

# 启动 code-server 容器并暴露在 http://127.0.0.1:8080
# 同时把当前目录挂载为容器内 /home/coder/project，并转发宿主机 UID/GID，
# 使容器内所有文件系统操作都以宿主机用户身份执行。
#
# $HOME/.config 会被挂载到容器内 $HOME/.config，便于在容器外直接访问
# 和修改 $HOME/.config/code-server/config.json。
mkdir -p ~/.config
docker run -it --name code-server -p 127.0.0.1:8080:8080 \
  -v "$HOME/.local:/home/coder/.local" \
  -v "$HOME/.config:/home/coder/.config" \
  -v "$PWD:/home/coder/project" \
  -u "$(id -u):$(id -g)" \
  -e "DOCKER_USER=$USER" \
  codercom/code-server:latest

官方镜像支持 amd64 与 arm64。从 ci/release-image/Dockerfile 可以看到官方镜像的构建方式：基于 debian:13，通过 dpkg -i 安装 code-server 的 .deb 包（即 Standalone 构建产物），预置 coder 用户（uid 1000）并安装 fixuid 修正挂载卷的所有权，入口为 ci/release-image/entrypoint.sh，默认以 --bind-addr 0.0.0.0:8080 启动；DOCKER_USER 环境变量正是示例命令中 -e 传入的那个，用于在转发 uid 后保持 docker-exec 的身份一致性。

七、Helm 部署

可以使用 Helm 包管理器将 code-server 部署到 Kubernetes。仓库内自带了完整的 Helm chart，见 ci/helm-chart/Chart.yaml 与 ci/helm-chart/values.yaml，模板涵盖 deployment.yaml、service.yaml、ingress.yaml、pvc.yaml、secrets.yaml 等；更完整的部署说明见 docs/helm.md。

八、Windows、Raspberry Pi、Termux 与云厂商

• Windows：官方目前不发布 Windows 原生发行版，通常借助 WSL、Docker 或虚拟机方式使用。
• Raspberry Pi：文档推荐通过 npm 安装（树莓派多为 arm 架构，不在 amd64/arm64 预编译范围内）。
• Termux：安装步骤请查阅专门的 docs/termux.md。
• 云厂商：项目为 DigitalOcean、Railway、Heroku、Azure 等维护有一键应用与安装脚本，可在各自云市场直接部署。

九、卸载 code-server

code-server 的卸载分两部分：删除应用目录 + 删除用户配置数据。

删除配置与数据：

rm -rf ~/.local/share/code-server ~/.config/code-server

各安装方式对应的应用删除命令：

install.sh 安装（默认位于 ~/.local/lib/code-server-<version>）：

rm -rf ~/.local/lib/code-server-*

Homebrew 安装：

brew remove code-server
# 等价写法
brew uninstall code-server

npm 安装：

npm uninstall --global code-server

Debian/Ubuntu：

sudo apt remove code-server

十、安装后的配置入口：源码视角

无论采用哪种安装方式，服务启动后都会提示相同的验证路径：访问 http://127.0.0.1:8080，密码在 ~/.config/code-server/config.yaml。这个路径来自 src/node/cli.ts 中 path.join(paths.config, "config.yaml") 的默认拼接，其中 paths 由 src/node/util.ts 引入的 xdg-basedir 包按 XDG 规范解析——这也是卸载章节中 ~/.config/code-server 与 ~/.local/share/code-server 两个目录的由来：前者存放 config.yaml（bind-addr、密码、认证方式等），后者存放扩展与运行时数据。

code-server 命令本身即 package.json 声明的 out/node/entry.js 入口，其 src/node/entry.ts 流程为：解析 CLI 参数 → 读取 config.yaml → 填充默认值 → 判断是否需要转发到 VS Code CLI 或复用已有实例 → 通过 wrapper 启动服务进程。因此安装完成后，除浏览器访问外，也可直接运行 code-server 前台调试，用 --help 查看全部参数，用 code-server --version 查看版本字符串（由 src/node/constants.ts 中的 getVersionString() 生成，包含 code-server 版本、commit 与内置 Code 版本）。

小结

code-server 的安装策略可以归纳为一条主线：优先系统包管理器，无发行版时回退 npm，Standalone 是全部产物链的基座。install.sh 通过 os()/arch()/distro() 三函数完成环境判定，用 npm_fallback 统一处理架构回退，并用 ~/.cache/code-server 缓存所有下载资产；npm 方式则面向无预编译包的架构、旧 glibc 与 Alpine/musl 环境，代价是需要本机 C 工具链在 postinstall 阶段编译原生模块。选择安装方式时，对照本文的检测参考表与 glibc/架构限制即可得出确定答案；安装后统一通过 http://127.0.0.1:8080 与 ~/.config/code-server/config.yaml 完成验证与后续配置。