code-server 保姆级部署教程：在浏览器里跑 VS Code 的轻量开源方案

一、项目介绍

code-server 是 Coder Technologies Inc. 维护的开源项目，把 Microsoft Visual Studio Code（VS Code）完整搬到服务器，通过浏览器即可访问一个功能完整的 VS Code 开发环境。官方文档原文："code-server" 即 "VS Code on a remote server"。

典型场景：
- 在低配笔记本上通过浏览器使用服务器上的开发环境；
- 在 iPad/平板上写代码；
- 统一团队开发环境，避免"我机器上能跑"的问题；
- 长时间运行的编译、训练任务放在服务器本地，不依赖本地网络。

项目在 GitHub（coder/code-server）持续活跃维护；官方同时提供 Cloud 托管版 coder.com（企业向）与开源自托管 code-server。

二、功能拆解

按官方文档与 VS Code 本身能力：

功能	说明
浏览器版 VS Code	完整 VS Code UI：文件树、编辑器、集成终端、调试器
扩展市场	可安装 VS Code 扩展（Python、Go、Prettier、Remote-SSH 等）
多平台安装	install.sh 自动识别 Debian/Ubuntu、Fedora/CentOS/RHEL、Arch、macOS、FreeBSD；不识别时回退到 standalone 包
多架构	官方镜像/包提供 amd64 与 arm64；arm32 需用社区镜像 linuxserver/code-server
密码 + HTTPS 自签	首次启动自动生成随机密码并写入 config.yaml
Docker 镜像	`codercom/code-server:latest`，amd64/arm64
systemd 服务	Debian/Ubuntu/RPM/Arch 安装后可 `systemctl enable --now code-server@$USER`

三、官方/GitHub 链接

GitHub 仓库：https://github.com/coder/code-server
官方文档（安装）：https://coder.com/docs/code-server/latest/install
官方网站：https://coder.com
安装脚本：https://code-server.dev/install.sh
Docker 镜像：https://hub.docker.com/r/codercom/code-server
Releases：https://github.com/coder/code-server/releases

四、环境要求

官方文档《Install》明确：

操作系统：Linux（Debian/Ubuntu、Fedora/CentOS/RHEL/SUSE、Arch、Artix）、macOS、FreeBSD；官方明确不发布 Windows 原生包（原文："We currently do not publish Windows releases"，issue #1397）。
glibc 要求：standalone 包要求 Linux glibc >= 2.28、glibcxx >= v3.4.21；不满足时用 npm 方式安装（官方文档「npm」一节）。
架构：官方发布 amd64 与 arm64；其他架构用 npm 方式。
端口：默认 8080（官方文档反复出现："Now visit http://127.0.0.1:8080"）。
配置文件：~/.config/code-server/config.yaml（密码、绑定地址、证书都在这里）。

五、部署步骤

官方文档推荐三种原生方式，本教程按官方原文给出最常用的两种。

方式 A：install.sh 一键脚本（官方推荐，Linux/macOS/FreeBSD）

步骤 1：（可选）dry-run 预览将要执行的命令

官方原文：

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

逐段解释：curl -fsSL 静默下载脚本；| sh 把脚本交给 shell 执行；-s -- --dry-run 是传给脚本的参数——--dry-run 让脚本只 echo 将要执行的命令而不真正执行。

预期输出参考： 输出一段将要执行的命令清单（如 sudo dpkg -i ... 或 tar -C ~/.local/lib -xz），不实际安装。

步骤 2：正式安装

官方原文：

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

逐段解释：同上，但去掉 --dry-run，真正执行安装。脚本会自动识别系统包管理器：
- Debian/Ubuntu → 安装 .deb；
- Fedora/CentOS/RHEL/openSUSE → 安装 .rpm；
- Arch → 安装 AUR 包；
- macOS 有 Homebrew → brew install；否则回退到 standalone 包到 ~/.local；
- FreeBSD / 其他架构 → 用 npm 安装。

预期输出参考： 官方原文："When done, the install script prints out instructions for running and starting code-server." 通常会出现类似 Installed extensions / Run: code-server 的提示；若安装到 ~/.local，脚本会提醒把 ~/.local/bin 加进 $PATH。

步骤 3：启动

code-server

逐段解释：直接运行 code-server 命令，前台启动。首次启动会在 ~/.config/code-server/config.yaml 生成随机密码与自签证书。

预期输出参考（官方文档原文）：

text [2026-xx-xxTxx:xx:xx.xxZ] info code-server v4.xx.x [2026-xx-xxTxx:xx:xx.xxZ] info HTTP server listening on http://127.0.0.1:8080/ [2026-xx-xxTxx:xx:xx.xxZ] info - Using password from ~/.config/code-server/config.yaml [2026-xx-xxTxx:xx:xx.xxZ] info - To get started, head to http://127.0.0.1:8080/

方式 B：Debian/Ubuntu .deb 包（官方原文）

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

逐段解释：把 $VERSION 替换为具体版本号（如 4.99.0，见 https://github.com/coder/code-server/releases ）；curl -fOL 下载 release 资产；dpkg -i 安装；systemctl enable --now 注册为 systemd 服务并立即启动，服务名带用户名后缀（code-server@$USER.service）。

方式 C：Docker（官方原文）

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

逐段解释（官方注释原文）：
- -p 127.0.0.1:8080:8080：把容器 8080 暴露到宿主 127.0.0.1:8080。
- -v "$HOME/.local:/home/coder/.local"：持久化扩展与用户数据。
- -v "$HOME/.config:/home/coder/.config"：持久化 code-server 配置（含密码）。
- -v "$PWD:/home/coder/project"：把当前目录挂载为容器内工作目录。
- -u "$(id -u):$(id -g)"：用宿主当前 UID/GID 运行，保证文件权限一致。
- -e "DOCKER_USER=$USER"：传用户名进容器。

六、配置参数详解

1. 配置文件 ~/.config/code-server/config.yaml（官方文档原文反复引用）：

首次启动自动生成，内容形如：

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

字段	默认值	说明
`bind-addr`	`127.0.0.1:8080`	监听地址；公网访问需改为 `0.0.0.0:8080`
`auth`	`password`	认证方式；可设为 `none`（仅内网）
`password`	随机生成	明文密码，登录时使用
`cert`	`false`（首次启动自动生成自签证书后为路径）	HTTPS 证书路径；`false` 表示 HTTP

2. 常用命令行参数（code-server --help 可见）：

code-server --bind-addr 0.0.0.0:8080 --auth password

官方文档提示：也可通过 --user-data-dir、--extensions-dir、--disable-telemetry 等参数覆盖默认目录（见 Artix Linux 一节示例）。

七、启动与运维

前台启动： code-server。
后台常驻（systemd，官方 .deb/RPM/AUR 方式自带）：
启动：sudo systemctl start code-server@$USER
停止：sudo systemctl stop code-server@$USER
开机自启：sudo systemctl enable --now code-server@$USER（官方原文命令）
查看日志：journalctl -u code-server@$USER -f
Docker 方式： 用 -d 替换 -it 即可后台运行；docker stop code-server / docker start code-server。
修改端口： 编辑 ~/.config/code-server/config.yaml 中 bind-addr，或启动时加 --bind-addr 0.0.0.0:9000。
卸载（官方文档原文）：

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

install.sh 方式额外：rm -rf ~/.local/lib/code-server-*；Debian/Ubuntu：sudo apt remove code-server；Homebrew：brew uninstall code-server；npm：npm uninstall --global code-server。

八、实操验证

浏览器访问 http://127.0.0.1:8080（服务器部署则为 http://服务器IP:8080，前提是 bind-addr 已改为 0.0.0.0:8080 且防火墙放行 8080）。
出现密码输入框——打开另一个终端，执行：

cat ~/.config/code-server/config.yaml

复制其中 password: 后面的字符串粘贴到浏览器。
3. 登录后看到完整 VS Code 界面：左侧文件树、中间编辑器、底部集成终端。
4. 打开终端（Ctrl+`），执行 pwd && ls，确认工作目录就是挂载/启动时的目录。
5. 安装一个扩展（如 Python）验证市场可用：左侧扩展图标 → 搜索 "Python" → Install。

登录与安全（重要）

官方默认密码： 无出厂固定密码。首次启动时自动在 ~/.config/code-server/config.yaml 中生成随机密码。
登录地址： http://127.0.0.1:8080（默认只监听本机）。
修改密码： 编辑 ~/.config/code-server/config.yaml 中 password: 字段，重启 code-server 生效。
密码重置： 删除 config.yaml 后重启 code-server，会重新生成随机密码；或手动改成自己想要的字符串。
密码存放位置： ~/.config/code-server/config.yaml（明文 YAML）。
安全提醒（强烈建议）：
1. 默认 bind-addr: 127.0.0.1:8080 只监听本机——公网服务器若直接改成 0.0.0.0:8080，等于把一个完整开发环境暴露在公网；务必：① 用强密码；② 前面套 Nginx/Caddy 做 HTTPS；③ 或用 SSH 隧道访问（ssh -L 8080:127.0.0.1:8080 user@server），不要改 bind-addr。
2. auth: none 仅在受信内网使用。

九、故障排查

案例 1：浏览器访问 8080 连接被拒绝

报错原文：This site can't be reached / ERR_CONNECTION_REFUSED。
报错原因：默认 bind-addr: 127.0.0.1:8080，只监听本机回环；远程浏览器自然连不上。
分步解决：① 公网部署时编辑 ~/.config/code-server/config.yaml 把 bind-addr 改为 0.0.0.0:8080；重启 code-server；② 或更安全的方式：保持 127.0.0.1:8080，本地用 SSH 隧道 ssh -L 8080:127.0.0.1:8080 user@server 后访问 http://127.0.0.1:8080。

案例 2：安装时报 node-gyp 错误（Raspberry Pi / 其他架构）

报错原文（官方文档 Raspberry Pi 一节引用 issue #5174）：node-gyp 编译失败。
报错原因：arm32 等官方未提供预编译二进制的架构，npm 方式需要本地编译原生模块。
分步解决：官方文档建议在 Raspberry Pi 上用 npm 方式安装；具体见 https://github.com/coder/code-server/issues/5174 ；arm32 用户也可用社区镜像 linuxserver/code-server（官方文档原文推荐）。

案例 3：Alpine Linux 上 standalone 包无法运行

报错原文（官方文档「npm」一节引用 issue #1430）：Error: dlopen ... /lib64/ld-linux-x86-64.so.2: no version information available 之类。
报错原因：官方 standalone 包要求 glibc ≥ 2.28；Alpine 用 musl libc，不兼容。
分步解决：官方建议改用 npm 方式安装 code-server（详见 docs/npm.md）。

案例 4：忘记密码

报错现象：浏览器密码输入框怎么输都进不去。
分步解决：cat ~/.config/code-server/config.yaml 查看当前密码；或直接编辑该文件把 password: 改成新值后重启。

十、升级、回滚与卸载

升级：
- install.sh 方式：重新执行 curl -fsSL https://code-server.dev/install.sh | sh（脚本会拉最新版）。
- .deb 方式：下载新版本 .deb 后 sudo dpkg -i code-server_<新版本>_amd64.deb。
- Docker 方式：

docker pull codercom/code-server:latest
docker stop code-server && docker rm code-server
# 重新执行方式 C 的 docker run 命令

回滚： 官方未提供一键回滚；从 https://github.com/coder/code-server/releases 下载旧版本 .deb 或 standalone 包覆盖安装即可（配置目录 ~/.config/code-server 保留）。

卸载： 见第七节官方卸载命令。

十一、商用许可合规说明

许可证：MIT License（仓库 LICENSE 文件开头原文："The MIT License / Copyright (c) 2019 Coder Technologies Inc."）。
MIT 许可允许自由使用、修改、分发与商用，包括闭源商业产品；必须保留原始版权声明与许可文本。
code-server 自托管无需付费授权；Coder 公司另提供 coder.com 企业版（商业产品），与开源 code-server 是两条线。
注意：code-server 本身是 MIT，但你在其中安装的 VS Code 扩展与打开的项目代码按各自许可证处理。