一、速览：code-server 到底是什么

入门

code-server 是开源项目 coder/code-server 提供的工具，它把完整的 VS Code（微软推出的免费代码编辑器）跑在后端服务器上，让你可以通过浏览器打开一个和本地几乎一模一样的编程界面。你不需要在自己的电脑上安装 VS Code，也不需要把代码文件同步来同步去。

它最大的价值是解决两个痛点：一是设备能力不足，比如用老旧笔记本或平板也能流畅写代码，因为编译、下载、测试等重活都发生在服务器上；二是环境不一致，不同设备打开同一个地址，看到的开发环境完全一样。

可以把 code-server 想象成一个“云端书房”：你的书、工具、书桌全都在云端，任何有浏览器的设备都只是进入这个书房的窗口。你不用随身携带沉重的工具，只需要开门即可。

二、快速部署：Docker 一把梭

入门

前置条件：你需要一台能联网的 Linux 服务器（也可以是本地电脑或虚拟机），建议至少 1GB 内存和 2 核 CPU，因为 code-server 和 VS Code 要占用一定资源。如果还没有服务器，可以先用一台闲置电脑或云服务商提供的最低配实例。

如果你使用 Docker（一种把软件打包成“集装箱”、随处可运行的工具），部署只需要一条命令。先确认服务器已安装 Docker：

docker --version

如果没有安装，可参考 Docker 官方文档先安装 Docker。安装完成后，运行以下命令启动 code-server：

docker run -d \
  --name=code-server \
  -e PASSWORD=yourpassword \
  -p 8080:8080 \
  -v "$PWD/project:/home/coder/project" \
  codercom/code-server:latest

说明：

• -d 表示在后台运行容器
• --name 给容器起个名字
• -e PASSWORD=yourpassword 设置访问密码，请把 yourpassword 改成自己的密码
• -p 8080:8080 把服务器的 8080 端口映射到容器内部的 8080 端口
• -v "$PWD/project:/home/coder/project" 把当前目录挂载到容器内的项目目录，这样代码文件会保存在服务器上，容器删除后数据不丢

启动后，在浏览器访问 http://服务器IP:8080，输入密码即可进入。注意：如果使用云服务器，需要在安全组中放行 8080 端口。

如果不想用 Docker，也可以使用官方一键安装脚本：

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

安装完成后，可运行 code-server 启动，默认端口也是 8080。但建议使用 Docker 方式，因为依赖更隔离，升级和卸载也更省心。

三、配置详解：环境变量、端口与数据卷

进阶 · 推荐细读

code-server 的默认配置已经适合单人使用，但了解几个核心参数会让你对部署更有掌控感。

环境变量：

其中 HASHED_PASSWORD 的生成方式可以在文档中查询，一般个人使用 PASSWORD 就够了。如果长时间暴露在公网，建议用加密密码或配合反向代理。

端口说明：

• 容器内默认端口是 8080，你可以通过 -p 服务器端口:8080 改成别的外部端口，避免冲突
• 如果同时部署多个 code-server 实例，每个实例需要映射到不同的外部端口

数据卷/挂载路径：

• /home/coder 是容器内用户主目录，所有代码、终端配置都放在这里
• 建议至少挂载一个目录到 /home/coder/project 或 /home/coder，否则删除容器后代码会消失
• 也可以挂载 .local/share/code-server 和 .local/share/ssh 等目录来持久化扩展和密钥

四、功能导览：像本地 VS Code 一样使用

入门

登录后，你会看到一个和桌面版 VS Code 几乎相同的界面：左侧有文件资源管理器、搜索、源代码管理、扩展、调试等图标，中间是编辑区，下方是集成终端。

几个重点功能：

• 扩展：点击左侧扩展图标，可以搜索并安装语言支持、主题、格式化工具等，扩展会安装在服务器上，重启后仍保留（需正确挂载数据卷）
• 终端：菜单栏选择“终端” -> “新终端”，即可打开服务器的命令行界面，适合运行安装命令、脚本等
• 文件同步：你可以把代码从 Git 仓库克隆下来，也可以把本地文件上传到挂载的目录，服务器就是你的主工作区

由于所有运算都在服务器上，即使你在平板或低配电脑上操作，也不会卡顿。如果服务器配置高，还可以用它跑大型项目的编译和测试。

五、常见问题：端口冲突、权限与数据持久化

入门

这里整理了新手最常遇到的几个问题。

端口冲突

如果 8080 端口被其他程序占用，启动容器时会报错。解决方法是换一个外部端口，例如：

docker run -d --name=code-server -e PASSWORD=yourpassword -p 8081:8080 codercom/code-server:latest

此时访问 http://服务器IP:8081 即可。

权限不足

容器内默认用户 coder 可能没有权限读写挂载的目录。常见现象是打开文件只能看不能改。建议把挂载目录的所有者设为 UID 1000（coder 用户），或在宿主机上提前 chown 调整权限。使用 Docker 时也可以用 -u root 参数启动，但会增加安全风险，不建议长期使用。

数据持久化

如果只用了 docker run 命令但没有挂载任何目录，删除容器后所有代码都会丢失。建议创建容器时就用 -v 参数把服务器上的目录挂载进去。需要备份时，直接备份宿主机上挂载的目录即可。

局域网/公网访问安全

如果只在家庭网络内使用，可以不用特别担心。如果放在公网服务器上，一定要设置强密码；更推荐的做法是使用反向代理加 HTTPS，下一节会介绍。

六、运维进阶：反向代理、HTTPS 与备份

进阶 · 推荐细读

如果你想通过域名访问 code-server，或者希望启用 HTTPS 加密传输，需要引入反向代理（一种在用户和你的服务之间转发的网关）。常用工具是 Caddy 或 Nginx。

以 Caddy 为例，它最大优点是自动申请并续期 HTTPS 证书。安装 Caddy 后，配置文件（通常叫 Caddyfile）可以这样写：

code.example.com {
    reverse_proxy localhost:8080
}

其中 code.example.com 需要替换成你自己的域名，并把域名的解析指向服务器 IP。保存配置后运行 caddy reload，稍等片刻，即可通过 https://code.example.com 访问 code-server。

如果使用 Nginx，也可以实现类似效果，但需要手动配置证书。Nginx 的 server 块中设置 proxy_pass http://127.0.0.1:8080;，并配置 WebSocket 支持，因为 code-server 依赖 WebSocket 实时通信。示例配置片段如下：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

升级策略：

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「sh」中文使用教程
• 「watchtower」中文使用教程
• 「awesome-ops-system」中文使用教程