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

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

【免费下载链接】code-serverVS Code in the browser项目地址: https://gitcode.com/GitHub_Trending/co/code-server

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 可用的安装参数

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

从 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）一一对应：

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

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.js24.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完成验证与后续配置。

【免费下载链接】code-serverVS Code in the browser项目地址: https://gitcode.com/GitHub_Trending/co/code-server