## 项目概述

code-server 是 Coder 团队开发的开源项目，它将微软的 VS Code 运行在远程服务器上，用户可以通过浏览器访问，获得一致的开发环境。项目采用 TypeScript 编写，基于 MIT 许可证发布，支持自托管部署，适用于个人开发者和团队协作场景。

## 核心功能

- **浏览器访问 VS Code**：在任何设备上通过浏览器使用完整的 VS Code 编辑器。
- **一致的开发环境**：所有代码、配置和扩展都保存在远程服务器上，确保环境一致性。
- **云端加速**：利用云服务器提升测试、编译、下载等密集型任务的性能。
- **内置代理**：支持通过子域名或子路径访问远程机器上的 Web 服务。
- **密码认证**：默认启用密码登录，并支持速率限制和哈希密码存储。
- **扩展市场**：默认使用 Open-VSX 扩展市场，也支持自定义市场。
- **多平台支持**：提供 Linux、macOS、FreeBSD 等平台的安装方式，支持 Docker、Helm 部署。
- **国际化**：支持自定义字符串和多种语言界面。

## 适用与不适用场景

**适用场景：**
- 个人开发者需要在不同设备上访问统一开发环境。
- 团队需要快速搭建远程开发环境，避免本地配置差异。
- 使用云服务器进行编译、测试等资源密集型任务。
- 需要在 iPad 等移动设备上进行代码编辑。

**不适用场景：**
- 需要微软官方扩展市场（如 Live Share、Remote SSH 等）的场景。
- 对浏览器兼容性要求极高，且无法升级浏览器的场景（较老浏览器可能不支持）。
- 需要多租户隔离的生产环境（建议使用虚拟机或 Coder 产品）。

## 技术架构与依赖

- **核心**：基于 VS Code 的开源核心，通过补丁方式集成。
- **语言**：TypeScript、Node.js（v24.x）。
- **依赖**：需要 Node.js、npm、git、git-lfs 等开发依赖；运行时需要 Linux 机器（1 GB RAM、2 vCPUs）并启用 WebSockets。
- **部署**：支持安装脚本、npm、Docker、Helm、系统包管理器（deb/rpm）等。

## 安装与快速开始

### 使用安装脚本（推荐）

```bash
# 预览安装过程
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run

# 执行安装
curl -fsSL https://code-server.dev/install.sh | sh
```

安装完成后，脚本会输出启动和运行 code-server 的说明。默认配置监听 `127.0.0.1:8080`，密码在 `~/.config/code-server/config.yaml` 中。

### 使用 Docker

```bash
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
```

### 使用 npm

```bash
npm install --global code-server
code-server
```

## 典型使用方法

- **启动服务**：运行 `code-server`，默认监听 `127.0.0.1:8080`，使用密码登录。
- **修改端口**：使用 `--bind-addr localhost:3000` 或环境变量 `PORT=3000`。
- **安装扩展**：在编辑器内通过扩展面板安装，或使用命令行 `code-server --install-extension <extension-id>`。
- **访问远程服务**：通过 `/proxy/<port>/` 或子域名（需配置 `--proxy-domain`）访问远程端口。
- **使用代理**：设置 `HTTP_PROXY`、`HTTPS_PROXY` 环境变量以代理服务器端请求。
- **健康检查**：访问 `/healthz` 端点检查服务状态。

## 配置与部署要点

- **配置文件**：默认位于 `~/.config/code-server/config.yaml`，支持 `bind-addr`、`auth`、`password`、`cert` 等配置项。
- **安全暴露**：不建议直接暴露到公网，推荐使用 SSH 端口转发、Let's Encrypt + Caddy/NGINX 或自签名证书。
- **反向代理**：需正确设置 `Host`、`Upgrade` 等头信息，确保 WebSocket 连接正常。
- **环境变量**：支持 `CODE_SERVER_HOST`、`CODE_SERVER_APP_NAME`、`EXTENSIONS_GALLERY` 等。
- **系统服务**：可通过 systemd 管理，支持 socket 激活（`--socket-fd`）。
- **多实例**：可通过 `--cookie-suffix` 避免 cookie 冲突。

## 限制、风险与许可证

- **许可证**：MIT 许可证。
- **扩展市场限制**：不能使用微软官方市场，默认使用 Open-VSX，部分扩展不可用。
- **安全风险**：直接暴露到公网可能导致机器被接管，必须启用认证和加密。
- **浏览器兼容性**：较老浏览器可能无法使用，需要支持 ES2022 等特性。
- **平台限制**：不提供 Windows 官方发布版，armhf 架构已停止支持。
- **已知问题**：自定义扩展调试不支持，扩展性能分析功能禁用。

## 官方链接

- GitHub 仓库：https://github.com/coder/code-server
- 官方文档：https://coder.com/docs/code-server/latest
- 安装脚本：https://code-server.dev/install.sh
- Docker 镜像：https://hub.docker.com/r/codercom/code-server
- npm 包：https://www.npmjs.com/package/code-server
- 发布页面：https://github.com/coder/code-server/releases

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CHANGELOG、docs 目录下的文档（FAQ、安装指南、贡献指南等）。
- 分析时间：2026-08-27（基于最新发布版本 v4.135.0 的日期）。