code-server部署配置全教程（安装、配置、换vscode官方源、解决c/c++插件不可用问题）

1. 引言

code-server 是一个开源的工具，可以让你在浏览器中使用 VSCode 而不需要安装任何软件。它可以让你在云服务器上部署开发环境，随时用平板或笔记本浏览器编码。

本文参考官方文档，结合常见需求整理，适合 Linux 用户（Debian/Ubuntu、Arch、RedHat 等发行版）。我们将介绍多种安装方式、基础配置、扩展市场配置以及修复 C/C++ 插件问题的步骤。

2. 安装

2.1 环境准备

先更新系统并安装基础依赖（根据发行版选择命令）：

• Debian/Ubuntu:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential gdb

• Arch:

sudo pacman -Syu
sudo pacman -S --needed curl git base-devel gdb

• Fedora / CentOS / RHEL:

sudo dnf update -y
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y curl git gdb

2.2 安装方式

如果你是新手小白，没有自己的云服务器，或担心云服务器维护困难，不稳定，也可以使用雨云的云应用，一键安装 code-server。

---

方式1：官方脚本

最简单的方法，适用于大多数 Linux 发行版。在系统终端中，运行以下命令：

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

脚本会自动检测系统类型，并尝试使用系统包管理器安装；若无对应包则回退到独立二进制安装（默认安装到 ~/.local）。

安装完成后，脚本会给出启动命令。

方式2：二进制文件

请自行进入 Releases 界面查看最新版本号。

对于 Debian:

wget https://github.com/coder/code-server/releases/download/v4.135.0/code-server_4.135.0_amd64.deb
dpkg -i code-server_4.135.0_amd64.deb

对于 RedHat:

wget https://github.com/coder/code-server/releases/download/v4.135.0/code-server-4.135.0-amd64.rpm
rpm -ivh https://github.com/coder/code-server/releases/download/v4.135.0/code-server-4.135.0-amd64.rpm

对于 Arch，得益于丰富的 aur 资源，可以直接使用 AUR 源中的 code-server 安装：

# 有yay
yay -S code-server
# 无yay
git clone https://aur.archlinux.org/code-server.git
cd code-server
makepkg -si

方式3: docker 安装

mkdir -p ~/.config/code-server
docker run -d \
  --name=code-server \
  -e PUID=1000 -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e PASSWORD=yourpassword \
  -e 'EXTENSIONS_GALLERY={"serviceUrl":"https://marketplace.visualstudio.com/_apis/public/gallery","cacheUrl":"https://vscode.blob.core.windows.net/gallery/index","itemUrl":"https://marketplace.visualstudio.com/items"}' \
  -p 8080:8080 \
  -v ~/.config/code-server:/config \
  --restart unless-stopped \
  lscr.io/linuxserver/code-server:latest
# 可自行更改端口号

3. 配置

默认配置在 ~/.config/code-server/config.yaml，首次启动后会自动生成，Docker 用户对应容器内 /config/config.yaml。

编辑 config.yaml，修改以下字段：

bind-addr: 0.0.0.0:8080   # 监听所有地址的 8080 端口（仅本地访问用 127.0.0.1）
auth: password            # 认证方式：password / none
password: your_secure_password  # 自定义密码
cert: false               # 是否启用 HTTPS（false 为 HTTP）

如果设置 auth: none，则无需密码，但强烈不建议在公网环境使用。

修改后需重启 code-server 生效。

配置完成后，运行：

systemctl --user enable --now code-server

访问 ip:8080 使用密码登录即可。

若需要使用特定域名访问，或者有统一端口需求，可配置 nginx 反向代理：

server {
    listen 80;
    server_name code.example.com;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Accept-Encoding gzip;
    }
}

4. 扩展市场换源

code-server 默认使用 Open VSX 市场，某些扩展可能缺失或版本滞后。若要使用微软官方市场，可通过设置环境变量或修改配置文件。编辑配置文件（Docker 安装中已经配置好）：

systemctl --user edit code-server

添加以下内容：

[Service]
Environment=EXTENSIONS_GALLERY={"serviceUrl":"https://marketplace.visualstudio.com/_apis/public/gallery","cacheUrl":"https://vscode.blob.core.windows.net/gallery/index","itemUrl":"https://marketplace.visualstudio.com/items"}

保存后重启。

sudo systemctl daemon-reload
sudo systemctl restart code-server

注意：使用官方市场可能受网络环境影响，国内服务器可能访问缓慢或失败，可考虑使用镜像或保留默认。

5. 修复 C/C++ 插件无法正常使用的问题

在 code-server 中安装 C/C++ 官方插件时，出现报错：

The C/C++ extension may be used only with Microsoft Visual Studio, Visual Studio for Mac, Visual Studio Code, Azure DevOps, Team Foundation Server, and successor Microsoft products and services to develop and test your applications.

这是微软收紧了插件的使用权，包括 Cursor 等基于 vscode 的项目都受到了影响。目前唯一的方案是安装 1.23.6 版本，并关闭自动更新。

6. 卸载

• 脚本安装（安装到 ~/.local）：

rm -rf ~/.local/lib/code-server-*
rm -f ~/.local/bin/code-server
rm -rf ~/.config/code-server ~/.local/share/code-server

• Debian / Ubuntu：

sudo apt remove code-server

• RedHat / Fedora：

sudo rpm -e code-server

• Arch Linux：

sudo pacman -Rns code-server

• Docker：停止并删除容器，然后删除镜像：

docker stop code-server
docker rm code-server
docker rmi lscr.io/linuxserver/code-server:latest
rm -rf ~/.config/code-server

7. 常见问题与故障排查（FAQ）

7.1 无法启动

症状：运行 code-server 或 systemd 服务时立即退出，或报错无法监听端口。

可能原因及解决方法

1. 端口被占用
   • 检查端口占用：sudo ss -tulpn | grep :8080（或你配置的端口）
   • 若被占用，可更换 config.yaml 中的 bind-addr 端口，或终止占用进程：sudo kill -9 <PID>
   • 注意：若使用 80 或 443 等特权端口，需要以 root 运行或赋予 CAP_NET_BIND_SERVICE 能力。
2. 配置文件语法错误
   • 检查 ~/.config/code-server/config.yaml 的 YAML 格式是否正确（缩进、冒号后空格）。
   • 使用 code-server --help 查看可用配置项，或临时用环境变量覆盖配置测试： code-server --bind-addr 0.0.0.0:8080 --auth none
   • 若启动成功，则说明配置文件有误，逐项检查修复。
3. 权限不足
   • 如果以普通用户安装，尝试以 sudo 启动可能引发权限混乱，建议使用用户级 systemd 服务或确保目录可写。
   • 检查数据目录（默认 ~/.local/share/code-server）和配置目录的属主： ls -ld ~/.config/code-server ~/.local/share/code-server
   • 若属主为 root，执行 sudo chown -R $USER:$USER ~/.config/code-server ~/.local/share/code-server。
4. 依赖缺失
   • 某些精简系统可能缺少 libxkbcommon、libgtk-3 等图形库（即使无头模式也需要）。根据发行版安装相应依赖，例如 Ubuntu： sudo apt install -y libxkbcommon0 libgtk-3-0 libgbm1

通用排查：查看详细日志

journalctl --user -u code-server -f          # 用户服务
sudo journalctl -u code-server -f            # 系统服务
code-server --verbose                         # 前台运行，输出调试信息

---

7.2 无法访问

症状：服务已启动，但浏览器无法打开页面。

可能原因及解决方法

1. 防火墙未放行
   • 检查防火墙状态： sudo ufw status # Ubuntu sudo firewall-cmd --list-all # Fedora/CentOS
   • 放行端口（以 8080 为例）： sudo ufw allow 8080/tcp sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload
   • 云服务器还需在安全组中开放对应端口。
2. 绑定地址为 127.0.0.1
   • 检查 config.yaml 中的 bind-addr，若为 127.0.0.1:8080，只能本机访问。
   • 改为 0.0.0.0:8080 以监听所有网络接口，或设置具体内网 IP（如 192.168.1.100:8080）。
3. 反向代理配置错误
   • 确保代理传递了必要的头信息，尤其是 Upgrade 和 Connection 用于 WebSocket。
   • Nginx 正确配置示例： location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 86400; }
   • 检查 Nginx 错误日志 /var/log/nginx/error.log，常见错误如 502（后端未启动）、404（路径错误）。
4. HTTPS 证书问题
   • 若启用 cert，确保证书和私钥路径正确且可读。
   • 使用自签名证书时，浏览器需手动信任；生产环境建议使用 Let's Encrypt 并通过反向代理终止 TLS。

---

7.3 扩展安装失败

症状：在扩展市场点击安装后长时间无响应，或报错“无法下载扩展”“XHR failed”。

可能原因及解决方法

1. 网络问题
   • 默认的 Open VSX 市场（open-vsx.org）可能因地域或防火墙访问缓慢。
   • 测试连通性：curl -I https://open-vsx.org
   • 解决方案：
     • 使用国内镜像市场，例如在 config.yaml 中添加： extensions-gallery: serviceUrl: https://registry.npmmirror.com/-/vscode/marketplace itemUrl: https://registry.npmmirror.com/-/vscode/item
     • 或通过代理服务器访问，设置环境变量 HTTPS_PROXY。
2. 市场 URL 配置错误
   • 环境变量 EXTENSIONS_GALLERY 必须是合法 JSON 且包含三个字段（serviceUrl、cacheUrl、itemUrl）。
   • 验证配置是否生效：启动后打开浏览器开发者工具，查看网络请求中的市场地址。
3. 证书问题
   • 企业代理或防火墙可能拦截 HTTPS 并替换证书，导致验证失败。
   • 临时禁用证书验证（不推荐）：设置环境变量 NODE_TLS_REJECT_UNAUTHORIZED=0。
   • 长期解决：将企业根证书导入系统信任库，或使用 --extensions-dir 手动安装 .vsix。
4. 权限不足
   • 扩展安装目录默认为 ~/.local/share/code-server/extensions，若不可写会导致失败。检查并修复： chmod 755 ~/.local/share/code-server/extensions
5. 手动安装
   • 从 Open VSX 或微软市场下载 .vsix 文件，然后运行： code-server --install-extension /path/to/extension.vsix

---

7.4 登录后白屏

症状：输入密码后页面空白，或短暂显示加载动画后无内容。

可能原因及解决方法

1. 浏览器缓存
   • 强制刷新：Ctrl+Shift+R（或 Cmd+Shift+R）。
   • 清除站点数据：浏览器设置 → 隐私与安全 → 清除浏览数据 → 选择“缓存的图片和文件”。
   • 更换浏览器或使用无痕模式测试。
2. WebSocket 被代理阻断
   • code-server 依赖 WebSocket 进行实时通信。若反向代理未正确转发 WebSocket 升级请求，会导致连接失败而白屏。
   • 检查代理配置中的 Upgrade 和 Connection 头（见 7.2 反向代理部分）。
   • 使用 Nginx 时，确认 proxy_read_timeout 足够长；Caddy 默认支持 WebSocket 无需额外配置。
3. 浏览器不支持或禁用 WebSocket
   • 尝试更换现代浏览器（Chrome/Firefox/Edge 最新版），并确保没有插件阻止 WebSocket。
4. 工作区加载错误
   • 删除工作区缓存：rm -rf ~/.local/share/code-server/User/workspaceStorage/* 后重启服务。
   • 尝试打开其他目录作为工作区，检查是否目录权限不足或包含损坏文件。
5. 服务端渲染错误
   • 查看 code-server 日志，搜索 ERROR 或 Stack trace。常见问题包括 Node.js 版本不兼容（要求 ≥ 18）。
   • 升级或降级 Node.js 版本，或使用官方打包的二进制文件（已内置正确版本）。

---

7.5 更新后插件丢失

症状：升级 code-server 后，之前安装的扩展全部消失。

原因分析

• code-server 默认将扩展安装在 ~/.local/share/code-server/extensions，该目录通常不会被覆盖。
• 若使用官方脚本升级，旧版本目录可能被清理；或在使用 Docker 时未挂载该目录。

解决方法

1. 确认扩展目录位置
   • 查看配置文件或启动日志中 extensions-dir 的路径： code-server --help | grep extensions-dir
   • 默认：~/.local/share/code-server/extensions。
2. 恢复备份
   • 若曾备份过该目录，直接复制回去。
   • 否则，重新安装所需扩展（建议记录常用扩展清单）。
3. 预防措施
   • Docker 部署：将扩展目录挂载到宿主机。在 docker run 命令中添加： -v ~/.config/code-server:/config
   • 原生安装：升级前备份： tar -czf code-server-extensions.tar.gz ~/.local/share/code-server/extensions
   • 配置独立扩展目录：在 config.yaml 中设置固定路径（例如 /opt/code-server-extensions），并确保升级过程不会清除该目录。
4. 自动同步
   • 使用 Settings Sync 插件或 Git 管理 extensions.json，在新环境中用命令行批量安装： cat extensions.txt | xargs -L1 code-server --install-extension

---

7.6 其他常见问题

• 忘记密码：编辑 config.yaml 中的 password 字段，重启服务即可。
• CPU 占用过高：可能是文件监视器（watcher）过多，增大 --max-memory 或使用 --disable-workspace-trust，禁用不需要的扩展。
• 中文乱码：在设置中搜索 files.encoding 改为 utf8，并安装中文字体： sudo apt install fonts-noto-cjk