code-server是唯一可行入口，因其专为无头Linux服务器设计，复用VSCode核心服务层，支持完整插件API且能通过反向代理暴露HTTPS接口，而桌面版VSCode在私有云中无法启动。
不能直接在私有云服务器上装 VSCode 桌面版插件，必须用 code-server 作为运行时载体，再叠加自研插件的后端服务与前端注入逻辑。
为什么 code-server 是唯一可行入口
VSCode 插件分两类：纯前端（Webview/Command）和含服务端逻辑（Language Server、Debug Adapter、Custom Editor）。私有云环境没有图形桌面，code 命令行版或 Electron 版本根本起不来；只有 code-server 是专为无头 Linux 服务器设计的远程服务实现，它复用了 VSCode 源码中的核心服务层，支持完整插件 API（包括 vscode.workspace.fs、vscode.debug 等），且能通过反向代理暴露 HTTPS 接口。
常见错误现象：npm install -g code 失败、code --install-extension 报 “No display specified”、插件启用后无响应——全是误把桌面版工具链当服务端用。
-
code-server必须用官方预编译包（如code-server-4.0.1-linux-amd64.tar.gz），不建议源码构建，避免 Node.js ABI 和 VSCode 内核版本错配 - 启动时需显式指定
--auth none或--auth password，禁用默认的 token 认证，否则前端插件调用vscode.env.asExternalUri会失败 - 若插件依赖本地 CLI 工具（如
git、python），需确保这些二进制文件在code-server进程的$PATH中，而非仅用户 shell 的 PATH
自研插件如何绕过 Marketplace 审核直装
私有云场景下，插件不能走 Extensions: Install from VSIX 手动上传（权限受限且无法批量部署），正确路径是：将插件打包为 VSIX 后，解压到 code-server 的 extensions 目录，并通过配置文件声明启用。
关键操作步骤：
- VSIX 解压后得到文件夹，命名格式必须为
publisher.name-x.y.z（如myteam.ai-helper-1.2.0），不能带空格或特殊字符 - 把该文件夹整个拷贝到
~/.local/share/code-server/extensions/（用户级）或/usr/lib/code-server/extensions/（全局级） - 在
code-server启动参数中加入--extensions-dir /path/to/extensions，强制指定目录，避免读取默认位置失败 - 插件的
package.json中main字段必须指向一个可被 Node.js require 的 JS 文件，且该文件不能使用import语法（code-server内置的 Node.js 不支持 ESM）
安全边界必须落在插件通信链路上
自研插件常需调用内部 API（如代码审查服务、GitLab Token 代理、敏感配置解密模块），但 code-server 默认禁止跨域请求，且所有前端发往后端的 HTTP 请求都会被其网关拦截并重写 Host 头。直接写 fetch("https://internal-api.example.com") 必然 403。
正确做法是利用 code-server 提供的代理机制：
- 在插件前端代码中，所有后端请求统一走
vscode.env.asExternalUri构造 URL，例如vscode.env.asExternalUri(Uri.parse("/api/review")) - 启动
code-server时添加--proxy-domain internal-api.example.com，并在反向代理（如 Nginx）中将/api/路径转发到真实服务 - 插件后端服务（如有）必须监听
127.0.0.1:xxxx，禁止绑定0.0.0.0，防止被集群内其他节点直连 - 若插件需执行 shell 命令（如
git commit），必须用vscode.workspace.fsAPI 读写文件，而非child_process.exec—— 后者在code-server沙箱中默认被禁用
权限收敛比功能更重要
很多团队卡在“插件能装上但用不了”，本质是没做最小权限裁剪。VSCode 插件默认拥有远超需要的权限：读取全部工作区文件、调用任意系统命令、访问全部环境变量。
生产环境必须做三件事：
- 在
package.json的capabilities字段里，只声明真正需要的权限，例如："untrustedWorkspaces": { "supported": false }（禁用非信任工作区）、"virtualWorkspaces": false（禁用内存虚拟工作区） - 用
code-server的--disable-extensions启动参数禁用所有非白名单插件，再用--extensions-dir单独挂载自研插件目录 - 在 Kubernetes 部署时，给
code-serverPod 设置securityContext.runAsNonRoot: true和readOnlyRootFilesystem: true，插件无法写入/tmp或修改自身代码
最容易被忽略的是插件的 activationEvents：设成 * 会导致每次打开编辑器都加载，拖慢冷启动；应精确匹配为 onCommand:myteam.review.code 或 onLanguage:python，按需激活。
