code-server 上手指南：在浏览器中运行 VS Code 的完整安装、配置与部署实践

本文围绕 code-server 项目的主文档展开，覆盖其核心定位、环境要求、五种启动方式、install.sh 安装脚本的完整参数与自动检测机制、手动安装方法，以及首次运行后的配置文件结构与安全暴露方式。读完后你将能够在一台 Linux/macOS 机器上完成 code-server 的安装、以 systemd 或 Docker 方式运行，并理解其默认配置（~/.config/code-server/config.yaml）中每一项的含义。

code-server 是什么

code-server 让 VS Code 运行在任意机器上，然后通过浏览器访问它。你可以把它理解为"跑在服务器上的 VS Code + 一个浏览器端代理"：所有编辑、编译、测试、下载等重活都发生在服务器端，浏览器只是一个渲染终端。

它的三个核心卖点（来自项目 README 的 Highlights）：

• 在任何设备上获得一致的开发环境——笔记本、平板、手机浏览器，看到的都是同一套代码、同一个终端；
• 利用云服务器加速——测试、编译、下载等耗时操作受益于服务器的算力与网络；
• 省电——所有密集任务都在服务器执行，移动设备的电池消耗大幅降低。

从项目结构看，这个"代理层"本身并不复杂：src/node/ 下是一组 TypeScript 模块（HTTP 路由、认证、WebSocket 代理、i18n 等），真正干活的 VS Code 服务端位于 lib/vscode/。npm 包的入口在 package.json 中声明为 out/node/entry.js，对应源码 src/node/entry.ts。

环境要求

官方要求非常轻量：

• 1 GB RAM、2 个 CPU 核心（TL;DR：一台启用了 WebSockets 的 Linux 机器）；
• 环境必须启用 WebSockets，因为 code-server 依赖 WebSocket 在浏览器与服务器之间通信。

任何 Linux 发行版都可以使用，但项目文档默认读者在 Debian 上操作（通常托管在 Google Cloud）。更完整的规格说明与 GCP 虚拟机的搭建步骤见 docs/requirements.md。该文档给出了在 Google Cloud 上创建一台 Debian Compute Engine 虚拟机的完整清单，要点包括：

1. 进入 Compute Engine > VM Instances，点击 Create Instance；
2. 选择离你最近的 region，zone 任选；
3. 选择 E2 series 通用型实例，切到 custom 并设置至少 2 核 / 2 GB 内存；
4. 强烈建议把启动盘换成 SSD Persistent Disk（至少 32 GB）；
5. 在 Networking 中把网卡改为静态内网 IP；
6. 在 Security > SSH Keys 添加你的公钥，点击 Create。

注意事项：不用时可以关机省钱；推荐用 gcloud cli 代替控制台操作；如果要走 HTTPS，建议准备一个外部域名配合 Let's Encrypt。

五种启动方式

项目 README 给出了从零开始的五条路径，下面结合仓库内容逐一说明：

1. install.sh 安装脚本（推荐）

脚本 install.sh 位于仓库根目录，能自动化大部分流程，并尽可能使用系统包管理器：

# 预览安装过程会执行哪些命令（不实际执行）
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run

# 正式安装
curl -fsSL https://code-server.dev/install.sh | sh

安装完成后，脚本会打印运行与启动 code-server 的说明。完整的脚本参数、检测规则与手动安装方法见 docs/install.md。

安装脚本的全部参数

install.sh 支持以下选项（在 --help 输出中逐一列出）：

参数	说明
--dry-run	只打印将执行的安装命令，不实际运行
--version X.X.X	安装指定版本而不是最新版
--edge	安装最新的 edge（预发布）版本
--method detect	默认方法：检测系统包管理器并优先使用
--method standalone	直接把独立发布包解包到 ~/.local
--prefix <dir>	独立包的安装前缀，默认 ~/.local；传 --prefix=/usr/local 可装到系统级
--rsh <bin>	远程安装时使用的远程 shell，默认 ssh
user@host	通过 SSH 在远程机器上安装（远程机器需能联网）

几个值得注意的实现细节（来自 install.sh 源码）：

• 远程安装：传入 user@host 后，脚本会用 curl | rsh 把自身再在远端执行一遍，等价于 sh -s -- "$ALL_FLAGS"；
• 缓存：所有下载的构件都缓存在 ~/.cache/code-server（可通过 XDG_CACHE_HOME 覆盖），重复安装不重复下载；
• 版本发现：稳定版通过跟随 releases/latest 重定向获取版本号，--edge 则解析 GitHub Releases API 的第一个条目；
• 独立包布局：解包到 ~/.local/lib/code-server-X.X.X，并在 ~/.local/bin/code-server 建立符号链接——记得把 ~/.local/bin 加入 $PATH；
• npm 回退：只有 amd64/arm64 的 Linux 与 amd64 的 macOS 有预编译发布包，其他架构会自动回退到 npm 安装（会本地编译原生模块，需要 Node 20+ 和若干 C 依赖）。

detect 方法的检测规则

脚本通过读取 /etc/os-release（含 ID_LIKE）识别发行版，然后按如下分支处理（main() 中的 case $DISTRO 分支）：

• Debian / Ubuntu / Raspbian：安装 GitHub 上的 .deb 包（dpkg -i）；
• Fedora / CentOS / RHEL / openSUSE：安装 GitHub 上的 .rpm 包（rpm -U）；
• Arch Linux：从 AUR 安装（拉取 AUR 快照后 makepkg -si）；
• FreeBSD / Alpine：只能走 npm（这两个平台没有预编译包）；
• macOS：有 Homebrew 就 brew install code-server，否则回退到独立包，再无预编译包时回退 npm；
• 其他一切系统：先尝试独立发布包，架构不支持则回退 npm。

这套检测逻辑有对应的 BATS 测试覆盖各种发行版/架构组合的行为，见 test/scripts/install.bats（例如 debian arm64 走 deb、arch i686 回退 npm 等用例）。

对于 curl | sh 的安全顾虑，官方在 docs/install.md 中引用了 sandstorm.io 关于"curl-bash 是否安全"的讨论作为参考。

2. 手动安装

如果不想用脚本，docs/install.md 提供了与脚本"完全一致命令"的手动流程，主要路径有：

独立发布包（standalone release）：每个版本都会发布自包含的 .tar.gz，内含 node 二进制与 node 模块；Linux 上要求 glibc >= 2.28、glibcxx >= v3.4.21：

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
# 访问 http://127.0.0.1:8080，密码在 ~/.config/code-server/config.yaml

Debian / Ubuntu：

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

Fedora / CentOS / RHEL / SUSE：

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

macOS：

brew install code-server
brew services start code-server

npm：当你的机器不是 amd64/arm64、glibc 过旧（< 2.28）或运行在 Alpine（非 glibc）上时，官方推荐 npm install -g code-server，安装时会编译原生模块，依赖说明见 docs/npm.md。

Docker：官方镜像支持 amd64 与 arm64，一条命令即可把当前目录挂载进去并把 UID/GID 透传到容器内：

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

Kubernetes 场景可使用仓库自带的 Helm Chart，位于 ci/helm-chart/（含 Deployment、Service、Ingress、Secrets 等模板），说明文档见 docs/helm.md。

3. 团队部署

• 用 coder/coder 在产品层面统一管理团队基础设施上的 code-server 实例（README 中提到的团队方案）；
• 通过各云厂商的一键部署（DigitalOcean、Railway、Heroku、Azure 等）快速拉起；
• 如果项目已在用 devcontainers，可以安装官方的 code-server devcontainer feature，把 code-server 直接带进容器。

首次运行：配置文件与默认行为

无论哪种安装方式，首次启动都会自动生成默认配置文件 ~/.config/code-server/config.yaml。默认内容在源码 src/node/cli.ts 的 defaultConfigFile 中定义：

bind-addr: 127.0.0.1:8080
auth: password
password: <自动生成的随机密码>
cert: false

这四点值得结合源码理解：

• 默认只监听 localhost：避免服务未经保护就暴露到网络（见 bindAddrFromAllSources 的默认值 localhost:8080）；
• 密码自动生成为随机值并写入配置（generatePassword，实现见 src/node/util.ts），登录页需要复制它；也可以用环境变量 $PASSWORD（明文）或 $HASHED_PASSWORD（argon2 哈希）覆盖，CLI 上直接传 --password 是被禁止的——parse() 中明确抛出"--password can only be set in the config file or passed in via $PASSWORD"；
• CLI 与配置文件的合并规则：配置文件的每个 YAML 键都会转换成等价的 --flag，再与命令行参数合并，命令行优先（setDefaults 中 Object.assign({}, configArgs, cliArgs)）；每个 flag 都直接映射为一个配置键，所以 code-server --help 的输出就是配置文件的键参考；
• 敏感环境变量会在子进程可见前被删除（delete process.env.PASSWORD 等），避免泄漏给 VS Code 子进程。

运行方式二选一：

# 作为 systemd 用户服务（deb/rpm 包提供 unit 文件）
sudo systemctl enable --now code-server@$USER

# 或者前台直接运行
code-server

启动日志会明确打印监听地址、认证状态（以及密码来源：配置文件还是 $PASSWORD/$HASHED_PASSWORD）与证书状态，见 src/node/main.ts 中 runCodeServer 的日志段落。

安全地把 code-server 暴露出去

安装完成后，下一步是暴露访问。docs/guide.md 是这一主题的权威指南，核心原则只有一条：绝不要在没有认证和加密的情况下直接把 code-server 暴露到互联网——终端接管意味着机器接管。

该指南覆盖的方案包括：

• SSH 端口转发（首选，无需额外配置）：把服务器上的 auth 改为 none、重启服务，然后本地执行 ssh -N -L 8080:127.0.0.1:8080 user@<instance-ip>，浏览器访问 http://127.0.0.1:8080；
• Let's Encrypt + Caddy 或 Let's Encrypt + NGINX：适合 iPad 等没有 SSH 客户端的设备，仓库的 ci/Caddyfile 就是一个现成的反代样例；
• 自签名证书：cert: true 时 code-server 会自行生成自签证书（生成逻辑见 src/node/util.ts 的 generateCertificate），作为最后手段，且与 iPad 不兼容。

几个与安全直接相关的实现事实：

• 默认 auth: password，且登录限流为每分钟 2 次、外加每小时 12 次；
• 提供 --trusted-origins 可关闭指定来源的 origin 校验（用于不便修改反代配置的场景）；
• --cert 不指定路径时自动生成自签证书，指定路径时必须同时提供 --cert-key（parse() 会强制检查）。

继续深入

• FAQ：常见问题（含移动端访问、WebSocket 故障排查等）见 docs/FAQ.md；
• 进阶使用：子域/子路径代理端口（/proxy/<port>、--proxy-domain）、国际化定制（--i18n、src/node/i18n/locales/ 内置 en/ja/th/ur/zh-cn 五个语言包）等详见 docs/guide.md；
• 特定平台：iOS（docs/ios.md）、iPad（docs/ipad.md）、Android/Termux（docs/android.md、docs/termux.md）都有专门文档；
• 贡献：开发与提交流程见 docs/CONTRIBUTING.md，测试体系包含单元（test/unit/）、集成（test/integration/）、端到端（test/e2e/，Playwright 驱动）与脚本测试（test/scripts/install.bats）。

最后提醒卸载方式（docs/install.md）：删除应用目录与用户数据即可彻底移除，例如 install.sh 安装的版本执行 rm -rf ~/.local/lib/code-server-*，并可用 rm -rf ~/.local/share/code-server ~/.config/code-server 清掉所有配置与数据。