1. 我为什么折腾code-server它到底值不值得装先说结论如果你手里有一台能让它长期跑着的服务器或开发机code-server值得装而且越早装越省事。它本质上是把VS Code整个编辑器塞进浏览器你在任何地方打开浏览器登录自己的密码就能进到一个和本地VS Code几乎一模一样的远程开发环境里代码、终端、插件、调试器全都跑在服务器那边浏览器只是个显示端。我在公司里负责维护几台Linux服务器平时经常要处理业务代码、改配置文件、帮同事看日志。以前最烦的就是四处装客户端、配SSH密钥、同步插件后来咬了咬牙上了code-server算是把这套流程彻底简化了。不夸张地说从那以后我连本地VS Code都不怎么开了浏览器书签里直接放一个code-server地址走到哪儿开发环境都跟着走。比较典型的场景是白天在办公室电脑上用浏览器进去写代码晚上回家用自己笔记本再开同一个地址工作进度完全无缝不用再花时间同步环境。这篇文章不是官方文档的翻译而是我自己完整跑通一遍的实操记录。我会把安装方式选型、首次配置、插件市场切换、C/C插件不生效这几个最容易出问题的点挨个说清楚。尤其是C/C插件的坑网上随手一搜全是装了插件还是不能用的求助我那边也卡了大半天排查链条比较完整这里一起分享出来。你照着做基本能少走80%的弯路。2. 安装方式的选择脚本安装、npm、Docker我最后用了哪种2.1 部署前的服务器基本盘先说硬件底线。我用的是2核4G的云服务器跑Ubuntu 22.04同时开了Nginx反代、一个MySQL、两个Java进程code-server还只是其中的一个整体负载可以接受。如果只是个人开发调试内存1G也能跑但编译大项目时明显吃力尤其是TypeScript、C这种吃内存的回升工程建议还是至少2G。存储方面code-server本体加上插件、编译缓存怎么也要预留10G以上毕竟你不可能只写Hello World。系统方面官方Linux二进制包支持Ubuntu/Debian/CentOS只要内核版本不太老就行。我这台服务器本身没有图形界面完全是纯命令行环境code-server配好之后通过浏览器访问所以不需要X11、Wayland这一堆依赖安装非常干净。2.2 官方脚本最快但可控性一般官方提供的安装方式非常简单直接执行这一段curl -fsSL https://code-server.dev/install.sh | sh脚本会自动识别你的发行版下载对应的deb或rpm包并安装装完还会提示你下一步做什么。如果你只是想快速在个人服务器上跑起来这个方案最短平快。我第一次装就是用的这个脚本整个过程大概一两分钟没遇到什么依赖问题。但是脚本也有它的局限性比如它默认安装的是当前发布的最新版可能有小版本更新导致行为变化另外它会创建systemd服务模板和默认配置目录后面你想改数据目录、端口什么的得自己知道去哪改。所以我的建议是脚本安装适合第一次体验或者测试环境正式使用的话最好还是自己手动维护。2.3 npm安装适合本身就在Node生态里的场景如果你服务器上本来就有Node.js环境也可以直接用npm全局安装npm install -g code-server --unsafe-perm注意那个--unsafe-perm参数很关键。npm在root权限下运行时默认会把它从配置里面去掉导致code-server的postinstall脚本没有权限写文件装完之后直接报错。加上这个参数之后权限问题就能绕过去。如果环境里装了nvm这种Node版本管理器还需要确保当前用户对全局node_modules目录有写权限否则同样会半途而废。另外npm装的是源代码版本启动时走的是JS入口理论上执行效率可能没有编译好的二进制高实际体感差别不大。但npm方式对Node版本要求比较严格官方要求Node 18以上太老的版本会出现兼容问题。所以如果你不是为了统一Node版本管理我不太推荐在服务器上用这种方式二进制包是更省心的选择。2.4 Docker方式适合隔离环境但数据卷要小心Code-server官方也提供了Docker镜像一条命令就能拉起来docker run -d --name code-server -p 8080:8080 \ -v $HOME/.config:/home/coder/.config \ -v $HOME/project:/home/coder/project \ -v $HOME/.local:/home/coder/.local \ codercom/code-server:latestDocker的好处是不污染宿主机环境升级就是拉新镜像重建容器回滚也特别方便。我身边很多同事喜欢这么用但我个人栽过一次跟头挂载目录的权限问题。容器里面的coder用户UID是1000如果你宿主机上挂载的目录权限不是1000容器里的code-server就没法往里面写文件插件装不上、编译产物也存不下来。我当时查了半天最后通过chown -R 1000:1000解决了。如果你要快速隔离Docker没问题但生产用还是得把权限检查清楚。2.5 我最终的选择二进制包手动安装折腾了几轮之后我最终选择了手动下载二进制tar包然后自己配置systemd开机自启。原因有三第一安装路径完全可控想放哪放哪第二不会像npm那样受全局Node版本牵连第三升级不过是下载新压缩包覆盖旧目录非常直观。到GitHub Releases页面找到code-server-{version}-linux-amd64.tar.gz解压之后把目录放到/usr/lib/code-server然后建立软链接sudo tar -xzf code-server-4.x.x-linux-amd64.tar.gz -C /usr/lib sudo mv /usr/lib/code-server-4.x.x-linux-amd64 /usr/lib/code-server sudo ln -s /usr/lib/code-server/bin/code-server /usr/local/bin/code-server这样就等于把code-server命令做成了全局命令。后面配置systemd、修改配置、启动服务就全是熟悉的套路了。3. 首次启动配置从能在浏览器上看到登录页到用起来顺手3.1 config.yaml里的字段我挨个讲清楚code-server启动后会读取~/.config/code-server/config.yaml这个文件如果不存在手动运行一次code-server让它自己生成一份默认配置再修改即可。我的配置文件长这样bind-addr: 0.0.0.0:8080 auth: password password: your-strong-password cert: false disable-telemetry: true disable-update-check: true这里的字段都不难但有三个值得重点说bind-addr如果你只想本机访问用127.0.0.1:8080最安全。但如果打算通过Nginx反代后对公网开放就一定得监听0.0.0.0否则反代转发到了地址却不是code-server在监听的地址会直接连接失败。auth我用的password模式单用户密码验证最简单。code-server还支持GitHub OAuth等更复杂的认证方式但对个人使用完全是杀鸡用牛刀。cert如果置为falsecode-server自己不会生成HTTPS证书纯HTTP访问。但这不意味着可以裸奔公网后面一定要用Nginx这类反向代理补上HTTPS。如果对安全要求极高可以让code-server自己处理证书把配置项改成证书路径但更常见、更好维护的方案还是反代统一终结TLS。另外我建议加上disable-telemetry和disable-update-check前者是关掉遥测上报减少一些无谓的流量和隐私担忧后者是关掉自动升级检查避免那个小红点一直弹窗也能减少启动时对外网连通状态的依赖。3.2 systemd服务脚本让它开机自启用二进制包安装之后自己写一个systemd服务是比较正规的做法。在/etc/systemd/system/code-server.service里写入[Unit] Descriptioncode-server Afternetwork.target [Service] Typesimple Useryour-user WorkingDirectory/home/your-user EnvironmentPASSWORDyour-strong-password ExecStart/usr/local/bin/code-server --config /home/your-user/.config/code-server/config.yaml Restartalways RestartSec10 [Install] WantedBymulti-user.target在这里我特意把密码通过Environment传递而不是写死在config.yaml里这样即使配置文件被意外看到的同事翻到密码也不是明文躺在那里。实际执行时如果环境变量PASSWORD存在会覆盖配置文件里的password字段优先级正好是环境变量更高。写完执行sudo systemctl daemon-reload sudo systemctl enable --now code-server正常跑起来之后浏览器打开http://服务器IP:8080输入密码就进到编辑界面了。第一次进入大概率会看到启动向导让你选择颜色主题、安装推荐扩展这些可以全部跳过后面再改也行。3.3 Nginx反代和HTTPS是我强烈建议补上的一层默认开着8080端口裸HTTP访问说实话我心里是不踏实的。密码认证虽然挡住了大多数人但明文密码传输在公网上始终是个隐患。我自己的做法是前面套一层Nginx用免费的Lets Encrypt证书把HTTPS终结掉再把/代理到code-server的8080端口。Nginx反代配置核心就这段server { listen 443 ssl; server_name code.example.com; ssl_certificate /etc/letsencrypt/live/code.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/code.example.com/privkey.pem; 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 X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }尤其注意Upgrade和Connection这两行code-server的编辑器有WebSocket通信不带上这两个头的话浏览器和服务器之间的实时通信会一直断开重连界面表现为连接已关闭反复弹。这个坑我印象太深了当初漏了这两行折腾了好一阵子才反应过来。至此code-server的本体算是能稳定服务了。但真正让它好用起来下一步是解决插件市场的问题。4. 把默认插件市场切换成官方VSCode源别再用那个阉割版商店4.1 为什么默认源看着能用实际上有很多插件装不上code-server默认配置的插件市场是Open VSX这是一个社区维护的VS Code兼容扩展市场本身没有问题很多插件在那儿都能搜到。但问题在于它的同步范围和维护速度跟微软官方源有差距。我在实际使用中遇到最典型的三类情况某些插件在Open VSX上搜不到或者官方源已经更新到2.xOpen VSX上还是1.x老版本版本差距大。部分插件依赖官方源的全局搜索接口代码补全、主题同步这些功能在Open VSX上行为就变得很诡异。还有极少数插件在Open VSX上的fork不是完整版装完一堆按钮是灰色的看了才知道是作者人在官方源更新这里没跟上。所以如果你想还原一个和本地VS Code完全一致的使用体验最直接的解决办法就是让code-server去连微软官方插件市场。4.2 如何让code-server读取官方源EXTENSIONS_GALLERY环境变量code-server是支持通过环境变量覆盖插件市场地址的。在启动code-server之前设置一个名为EXTENSIONS_GALLERY的环境变量它的值是一个JSON数组配置了官方VS Code市场相关的一组URL。我用的完整配置是下面这一串export 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, resourceUrlTemplate: https://{publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/{publisher}/extension/{name}/{version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage, controlUrl: https://marketplace.visualstudio.com}]如果你用的是systemd托管就不要在shell里export了直接在/etc/systemd/system/code-server.service的[Service]段加一行EnvironmentEXTENSIONS_GALLERY[{\serviceUrl\:\https://marketplace.visualstudio.com/_apis/public/gallery\,\cacheUrl\:\https://vscode.blob.core.windows.net/gallery/index\,\itemUrl\:\https://marketplace.visualstudio.com/items\,\resourceUrlTemplate\:\https://{publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/{publisher}/extension/{name}/{version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage\,\controlUrl\:\https://marketplace.visualstudio.com\}]改完重启服务让环境变量生效sudo systemctl daemon-reload sudo systemctl restart code-server这里有个很关键的点设置完环境变量之后如果code-server之前已经启动过、已经生成了本地插件缓存有可能还是显示旧的插件列表。我建议在浏览器端清一下站点数据或者干脆把~/.local/share/code-server/extensions目录重命名备份一下然后重启code-server让它重新拉取市场索引这样能避免一堆陈旧的扩展列表在界面里残留。4.3 怎么确认切换生效了验证方式很简单打开code-server的扩展面板直接搜索一个在Open VSX上很难搜到但官方源很热门的插件比如GitLens。如果现在能搜到并且版本号很新说明官方源已经生效了。其次可以看扩展页面的相关扩展推荐官方源的推荐逻辑比Open VSX丰富得多能明显感觉到智能度提高。另一个辅助验证方法是看日志在code-server启动日志里搜索ExtensionGallery能看到读取到的市场地址是不是官方源的域名。如果还是Open VSX的地址多半是环境变量没传给进程检查systemd配置或你启动时的shell环境。4.4 切换到官方源之后可能遇到的小插曲换源之后有几天,我发现插件安装偶尔会卡在下载阶段,扩展包怎么都拉不下来。排除了环境变量配置错误之后,基本可以确定是服务器到官方VS Code市场服务器的网络链路不太稳定。这个问题不是单独改配置能解决的,我更建议把插件提前下载好,用离线方式安装。毕竟code-server也支持直接上传.vsix文件安装。操作方法是把需要的VSIX包下载到服务器上,然后在扩展面板右上角的...菜单里选择Install from VSIX,或者用命令行:code-server --install-extension ./path/to/extension.vsix离线安装的优点是不用担心网络抖动导致半途而废,而且安装速度通常更快。插件版本方面,建议优先选和本地VS Code相同或相近的版本,避免依赖差异引起兼容问题。5. C/C插件不可用问题的完整排查链路从报错到彻底解决5.1 现象描述装了插件但代码始终没有智能补全我最初在code-server里写一个C项目,装了微软官方的C/C扩展(插件ID是ms-vscode.cpptools)。扩展面板显示已安装,状态列也是正常的,但打开任意一个.cpp文件,红色波浪线、代码补全、跳转定义全部没有,只有最简单的语法高亮是正常的。状态栏右下角一直显示正在加载IntelliSense...或者那个小齿轮图标转个不停,点开还能看到一堆语言服务错误。最气的是,代码的编译本身没问题,用g手工编译能出二进制,但编辑器就是死活不提供智能分析。这种能编译但IDE不识别的场景,明显不是代码的问题,而是插件和后端语言服务没有正常联动。5.2 先把最基础的MIS检查清单过一遍遇到这类问题,我的习惯是先按下面的清单过一遍,防止在小细节上浪费太多时间:确认code-server的版本和C/C插件版本匹配。C/C扩展对code-server的版本要求比较苛刻,某些新版本插件需要更晚的VS Code API,如果你code-server还停留在4.x早期,插件强行装最新版可能会不健全。确认插件安装用户和code-server运行用户一致。如果你用root启动code-server,但插件是普通用户装的,插件根本加载不到。确认服务器上安装了必要的编译工具链。C/C扩展自带的语言服务需要底层编译器来解析标准库头文件,没有gcc/g或clang,它连iostream都找不到。确认项目的.vscode目录下没有历史遗留的冲突配置。如果之前配置过clangd或者别的C/C相关插件,残留设置会干扰cpptools的激活。我当时第一次排查时就是卡在编译工具链上——我安装的是最小化Ubuntu系统,服务器上压根没有build-essential。补上之后虽然IntelliSense能起来了,但又有新的问题,就是下面要说的头文件搜索路径。5.3 根本原因之一C/C扩展不知道你的编译器在哪、标准库头文件在哪C/C扩展的IntelliSense机制,需要在项目里明确告诉它三件事:编译器路径、头文件搜索路径、C标准版本。正常情况下这些信息可以从编辑器打开的文件夹自动推断,但远程环境里配置经常识别不准,尤其是项目依赖一些自定义头文件目录时。我解决的方式是手动为项目生成一份c_cpp_properties.json。用编辑器命令面板搜索C/C: Edit Configurations (JSON),会生成一个名为.vscode/c_cpp_properties.json的文件。内容大致如下:{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /usr/include, /usr/local/include, /usr/include/x86_64-linux-gnu/c/12, /usr/include/c/12 ], defines: [], compilerPath: /usr/bin/g, cStandard: c17, cppStandard: c17, intelliSenseMode: linux-gcc-x64 } ], version: 4 }这里面的includePath非常关键。你不需要把所有头文件路径都手工写完整,但至少要确保常见系统的头文件目录在里面。我建议在服务器终端执行:echo | g -E -x c -v - 21 | grep ^ /这一串命令会把g查找头文件的完整路径列出来,里面有/usr/include/c/12、/usr/include/x86_64-linux-gnu等一系列目录。把输出里的路径尽量补到includePath数组里,IntelliSense的红色波浪线基本就能消掉一大半。如果你的项目引入了第三方库,比如boost、OpenCV、grpc这些,擅自改全局includePath并不是好主意,更合理的做法是用compile_commands.json或者CMake的插件去驱动。这里我们先把最简单方案搞定再说。5.4 根本原因之二插件版本和code-server底层Node版本不兼容除了配置文件问题,C/C扩展还有一个非常隐蔽的坑:它内置的语言服务对Node/Nodene版本很敏感。code-server本身是Node服务,插件运行在Node环境里,而cpptools的native模块需要匹配的Node ABI版本。如果你code-server升级到了新版本,而插件市场里的cpptools还是按旧Node版本编译的,启动时会报NODE_MODULE_VERSION不匹配一类的错误。遇到这种情况,解决办法通常是升级插件到最新版本,或者回退到上一个稳定版本。打开扩展面板,找到C/C扩展,右键选择Install Specific Version,我试过最稳的一个组合是code-server 4.x C/C v1.18.x,这个组合在多个环境里跑都没问题。如果官方源主版本已经更新到2.x,也不要害怕,可以先装最新版试一下,如果报错就装回1.x老版本,两者都有支持。5.5 我后来改用clangd的替代方案以及为什么现在还留着它在cpptools折腾了不小时间之后,我也尝试了另一个方案:换成clangd插件。clangd是Clang项目自带的C/C语言服务器,补全快、响应快,深度集成compile_commands.json。如果你项目本身就是用CMake或者Makefile管理,那么clangd可以读取编译数据库,智能补全的准确度高到能当作真香来形容。安装clangd插件之前,先确保服务器上装了clangd:sudo apt install clangd然后通过扩展面板安装llvm-vs-code-extensions.vscode-clangd。首次启动插件会提示你选择clangd二进制路径,用which clangd找到后填进去即可。如果项目没有自动生成compile_commands.json,可以借助Bear工具:bear -- make生成该文件后,clangd就知道每个源文件的编译参数。这一步完成之后,我再去仓库里跑代码,跳转精度、自动补全响应速度都比原来cpptools好不少。所以我的建议是:如果遇到C/C插件不可用,先试本文提到的cpptools配置调整,如果依旧不行,直接换clangd,不要再纠结。5.6 C/C问题的其他常见诱因权限、缓存、和远程环境隔离除了上面几条,我还遇到过一个特别像玄学的问题:cpptools的缓存损坏。现象是插件能激活,但是IntelliSense一直转圈,偶尔能出结果,过一会儿又消失。后来我发现它的状态缓存放在~/.cache/cpptools目录下,删除后重启code-server就恢复了。所以如果你前面的配置都没问题,不妨试试:rm -rf ~/.cache/cpptools另外注意,code-server远程环境里,编译器和头文件路径都是服务器上的,不是本地开发机的。如果你在本地Windows上写惯了,依赖本机的SDK路径,迁到服务器上一律要重新适配。这一点也是初学者问我最多的地方。6. 部署完之后,我的性能调优和日常维护经验6.1 限制内存使用量,避免和业务进程抢资源code-server本质是Node服务,启动时如果不做特殊限制,默认最大堆内存会是系统可用内存的一半左右。在我那台4G服务器上,它一度吃掉了1.5G内存,虽然能接受,但和别的服务一起跑还是不放心。所以我在systemd服务里加了一段环境变量:EnvironmentNODE_OPTIONS--max-old-space-size2048这样Node进程的堆上限被限制在2G,配合swap空间,整体运行稳定很多。如果你的项目很大、经常加载大型工程文件,可以适当调大一点,但没必要一上来就给到4G,先看实际占用再决定。6.2 关掉遥测和更新检查,减少无谓流量在config.yaml里加上disable-telemetry: true和disable-update-check: true是我强烈建议的做法。可能在可视化界面上没什么感觉,但实际体感是启动速度略快,而且不会时不时弹出新版本可用的提示,后台也少了一些外部请求。想要进一步减少UI卡顿,还可以在code-server设置里关掉编辑器里的Workbench: Startup Editor和Window: Zoom Per Scroll Wheel这些视觉效果。6.3 数据目录的备份与迁移code-server的用户数据存储规则基本和VS Code一致,插件装在~/.local/share/code-server/extensions,用户配置在~/.local/share/code-server/User,工作区状态和最近打开的历史也都在~/.local/share/code-server里。如果你要把环境迁移到新服务器,最省事的办法是:新机器按照本文步骤装好code-server,然后把旧服务器的~/.local/share/code-server完整打包拷过去,再启动服务。我每次迁移都是先停服务再打包:sudo systemctl stop code-server tar -zcf code-server-data.tar.gz -C ~/.local/share code-server然后放到新服务器解压,再systemctl start code-server,基本上打开就是一个一模一样的开发环境。注意备份时关掉code-server,否则有些缓存文件正在写,可能会拷出半个写了一半的状态。6.4 遇到奇怪的web UI卡顿,先不要把锅甩给服务器code-server界面卡顿很多时候不是服务器配置不够,而是浏览器端的WebSocket连接不稳定。最典型的症状是编辑器能打开,但输入字符延迟明显,重连之后又正常。排查思路一般是先把Nginx反代的WebSocket超时时间调大一些,在server块里加上:proxy_read_timeout 3600s; proxy_send_timeout 3600s;或者确认你是不是开着多个浏览器tab同时连同一个code-server实例单个实例处理多个WebSocket连接时并发性能会下降这时候要么关掉多余的tab要么考虑给不同项目跑多个实例。我自己的习惯是日常开发开一个实例如果需要同时看两个项目直接开两个端口跑两个实例互相不干扰。配置上把两个实例的端口区分开就行上面提到的systemd配置可以复制一份换Name和ExecStart里参数即可。这套环境用到现在已经有几个月了中途除了换过一次证书、清理过一次插件缓存之外基本没再出过幺蛾子。如果你也打算把日常开发环境迁到code-server上建议按这个顺序来先装二进制包、配systemd、设置官方源、再把C/C扩展或者clangd调好最后性能优化和备份手段一上就能当主力环境用了。
code-server远程开发环境搭建：从安装到C/C++插件问题排查
1. 我为什么折腾code-server它到底值不值得装先说结论如果你手里有一台能让它长期跑着的服务器或开发机code-server值得装而且越早装越省事。它本质上是把VS Code整个编辑器塞进浏览器你在任何地方打开浏览器登录自己的密码就能进到一个和本地VS Code几乎一模一样的远程开发环境里代码、终端、插件、调试器全都跑在服务器那边浏览器只是个显示端。我在公司里负责维护几台Linux服务器平时经常要处理业务代码、改配置文件、帮同事看日志。以前最烦的就是四处装客户端、配SSH密钥、同步插件后来咬了咬牙上了code-server算是把这套流程彻底简化了。不夸张地说从那以后我连本地VS Code都不怎么开了浏览器书签里直接放一个code-server地址走到哪儿开发环境都跟着走。比较典型的场景是白天在办公室电脑上用浏览器进去写代码晚上回家用自己笔记本再开同一个地址工作进度完全无缝不用再花时间同步环境。这篇文章不是官方文档的翻译而是我自己完整跑通一遍的实操记录。我会把安装方式选型、首次配置、插件市场切换、C/C插件不生效这几个最容易出问题的点挨个说清楚。尤其是C/C插件的坑网上随手一搜全是装了插件还是不能用的求助我那边也卡了大半天排查链条比较完整这里一起分享出来。你照着做基本能少走80%的弯路。2. 安装方式的选择脚本安装、npm、Docker我最后用了哪种2.1 部署前的服务器基本盘先说硬件底线。我用的是2核4G的云服务器跑Ubuntu 22.04同时开了Nginx反代、一个MySQL、两个Java进程code-server还只是其中的一个整体负载可以接受。如果只是个人开发调试内存1G也能跑但编译大项目时明显吃力尤其是TypeScript、C这种吃内存的回升工程建议还是至少2G。存储方面code-server本体加上插件、编译缓存怎么也要预留10G以上毕竟你不可能只写Hello World。系统方面官方Linux二进制包支持Ubuntu/Debian/CentOS只要内核版本不太老就行。我这台服务器本身没有图形界面完全是纯命令行环境code-server配好之后通过浏览器访问所以不需要X11、Wayland这一堆依赖安装非常干净。2.2 官方脚本最快但可控性一般官方提供的安装方式非常简单直接执行这一段curl -fsSL https://code-server.dev/install.sh | sh脚本会自动识别你的发行版下载对应的deb或rpm包并安装装完还会提示你下一步做什么。如果你只是想快速在个人服务器上跑起来这个方案最短平快。我第一次装就是用的这个脚本整个过程大概一两分钟没遇到什么依赖问题。但是脚本也有它的局限性比如它默认安装的是当前发布的最新版可能有小版本更新导致行为变化另外它会创建systemd服务模板和默认配置目录后面你想改数据目录、端口什么的得自己知道去哪改。所以我的建议是脚本安装适合第一次体验或者测试环境正式使用的话最好还是自己手动维护。2.3 npm安装适合本身就在Node生态里的场景如果你服务器上本来就有Node.js环境也可以直接用npm全局安装npm install -g code-server --unsafe-perm注意那个--unsafe-perm参数很关键。npm在root权限下运行时默认会把它从配置里面去掉导致code-server的postinstall脚本没有权限写文件装完之后直接报错。加上这个参数之后权限问题就能绕过去。如果环境里装了nvm这种Node版本管理器还需要确保当前用户对全局node_modules目录有写权限否则同样会半途而废。另外npm装的是源代码版本启动时走的是JS入口理论上执行效率可能没有编译好的二进制高实际体感差别不大。但npm方式对Node版本要求比较严格官方要求Node 18以上太老的版本会出现兼容问题。所以如果你不是为了统一Node版本管理我不太推荐在服务器上用这种方式二进制包是更省心的选择。2.4 Docker方式适合隔离环境但数据卷要小心Code-server官方也提供了Docker镜像一条命令就能拉起来docker run -d --name code-server -p 8080:8080 \ -v $HOME/.config:/home/coder/.config \ -v $HOME/project:/home/coder/project \ -v $HOME/.local:/home/coder/.local \ codercom/code-server:latestDocker的好处是不污染宿主机环境升级就是拉新镜像重建容器回滚也特别方便。我身边很多同事喜欢这么用但我个人栽过一次跟头挂载目录的权限问题。容器里面的coder用户UID是1000如果你宿主机上挂载的目录权限不是1000容器里的code-server就没法往里面写文件插件装不上、编译产物也存不下来。我当时查了半天最后通过chown -R 1000:1000解决了。如果你要快速隔离Docker没问题但生产用还是得把权限检查清楚。2.5 我最终的选择二进制包手动安装折腾了几轮之后我最终选择了手动下载二进制tar包然后自己配置systemd开机自启。原因有三第一安装路径完全可控想放哪放哪第二不会像npm那样受全局Node版本牵连第三升级不过是下载新压缩包覆盖旧目录非常直观。到GitHub Releases页面找到code-server-{version}-linux-amd64.tar.gz解压之后把目录放到/usr/lib/code-server然后建立软链接sudo tar -xzf code-server-4.x.x-linux-amd64.tar.gz -C /usr/lib sudo mv /usr/lib/code-server-4.x.x-linux-amd64 /usr/lib/code-server sudo ln -s /usr/lib/code-server/bin/code-server /usr/local/bin/code-server这样就等于把code-server命令做成了全局命令。后面配置systemd、修改配置、启动服务就全是熟悉的套路了。3. 首次启动配置从能在浏览器上看到登录页到用起来顺手3.1 config.yaml里的字段我挨个讲清楚code-server启动后会读取~/.config/code-server/config.yaml这个文件如果不存在手动运行一次code-server让它自己生成一份默认配置再修改即可。我的配置文件长这样bind-addr: 0.0.0.0:8080 auth: password password: your-strong-password cert: false disable-telemetry: true disable-update-check: true这里的字段都不难但有三个值得重点说bind-addr如果你只想本机访问用127.0.0.1:8080最安全。但如果打算通过Nginx反代后对公网开放就一定得监听0.0.0.0否则反代转发到了地址却不是code-server在监听的地址会直接连接失败。auth我用的password模式单用户密码验证最简单。code-server还支持GitHub OAuth等更复杂的认证方式但对个人使用完全是杀鸡用牛刀。cert如果置为falsecode-server自己不会生成HTTPS证书纯HTTP访问。但这不意味着可以裸奔公网后面一定要用Nginx这类反向代理补上HTTPS。如果对安全要求极高可以让code-server自己处理证书把配置项改成证书路径但更常见、更好维护的方案还是反代统一终结TLS。另外我建议加上disable-telemetry和disable-update-check前者是关掉遥测上报减少一些无谓的流量和隐私担忧后者是关掉自动升级检查避免那个小红点一直弹窗也能减少启动时对外网连通状态的依赖。3.2 systemd服务脚本让它开机自启用二进制包安装之后自己写一个systemd服务是比较正规的做法。在/etc/systemd/system/code-server.service里写入[Unit] Descriptioncode-server Afternetwork.target [Service] Typesimple Useryour-user WorkingDirectory/home/your-user EnvironmentPASSWORDyour-strong-password ExecStart/usr/local/bin/code-server --config /home/your-user/.config/code-server/config.yaml Restartalways RestartSec10 [Install] WantedBymulti-user.target在这里我特意把密码通过Environment传递而不是写死在config.yaml里这样即使配置文件被意外看到的同事翻到密码也不是明文躺在那里。实际执行时如果环境变量PASSWORD存在会覆盖配置文件里的password字段优先级正好是环境变量更高。写完执行sudo systemctl daemon-reload sudo systemctl enable --now code-server正常跑起来之后浏览器打开http://服务器IP:8080输入密码就进到编辑界面了。第一次进入大概率会看到启动向导让你选择颜色主题、安装推荐扩展这些可以全部跳过后面再改也行。3.3 Nginx反代和HTTPS是我强烈建议补上的一层默认开着8080端口裸HTTP访问说实话我心里是不踏实的。密码认证虽然挡住了大多数人但明文密码传输在公网上始终是个隐患。我自己的做法是前面套一层Nginx用免费的Lets Encrypt证书把HTTPS终结掉再把/代理到code-server的8080端口。Nginx反代配置核心就这段server { listen 443 ssl; server_name code.example.com; ssl_certificate /etc/letsencrypt/live/code.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/code.example.com/privkey.pem; 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 X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }尤其注意Upgrade和Connection这两行code-server的编辑器有WebSocket通信不带上这两个头的话浏览器和服务器之间的实时通信会一直断开重连界面表现为连接已关闭反复弹。这个坑我印象太深了当初漏了这两行折腾了好一阵子才反应过来。至此code-server的本体算是能稳定服务了。但真正让它好用起来下一步是解决插件市场的问题。4. 把默认插件市场切换成官方VSCode源别再用那个阉割版商店4.1 为什么默认源看着能用实际上有很多插件装不上code-server默认配置的插件市场是Open VSX这是一个社区维护的VS Code兼容扩展市场本身没有问题很多插件在那儿都能搜到。但问题在于它的同步范围和维护速度跟微软官方源有差距。我在实际使用中遇到最典型的三类情况某些插件在Open VSX上搜不到或者官方源已经更新到2.xOpen VSX上还是1.x老版本版本差距大。部分插件依赖官方源的全局搜索接口代码补全、主题同步这些功能在Open VSX上行为就变得很诡异。还有极少数插件在Open VSX上的fork不是完整版装完一堆按钮是灰色的看了才知道是作者人在官方源更新这里没跟上。所以如果你想还原一个和本地VS Code完全一致的使用体验最直接的解决办法就是让code-server去连微软官方插件市场。4.2 如何让code-server读取官方源EXTENSIONS_GALLERY环境变量code-server是支持通过环境变量覆盖插件市场地址的。在启动code-server之前设置一个名为EXTENSIONS_GALLERY的环境变量它的值是一个JSON数组配置了官方VS Code市场相关的一组URL。我用的完整配置是下面这一串export 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, resourceUrlTemplate: https://{publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/{publisher}/extension/{name}/{version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage, controlUrl: https://marketplace.visualstudio.com}]如果你用的是systemd托管就不要在shell里export了直接在/etc/systemd/system/code-server.service的[Service]段加一行EnvironmentEXTENSIONS_GALLERY[{\serviceUrl\:\https://marketplace.visualstudio.com/_apis/public/gallery\,\cacheUrl\:\https://vscode.blob.core.windows.net/gallery/index\,\itemUrl\:\https://marketplace.visualstudio.com/items\,\resourceUrlTemplate\:\https://{publisher}.gallery.vsassets.io/_apis/public/gallery/publisher/{publisher}/extension/{name}/{version}/assetbyname/Microsoft.VisualStudio.Services.VSIXPackage\,\controlUrl\:\https://marketplace.visualstudio.com\}]改完重启服务让环境变量生效sudo systemctl daemon-reload sudo systemctl restart code-server这里有个很关键的点设置完环境变量之后如果code-server之前已经启动过、已经生成了本地插件缓存有可能还是显示旧的插件列表。我建议在浏览器端清一下站点数据或者干脆把~/.local/share/code-server/extensions目录重命名备份一下然后重启code-server让它重新拉取市场索引这样能避免一堆陈旧的扩展列表在界面里残留。4.3 怎么确认切换生效了验证方式很简单打开code-server的扩展面板直接搜索一个在Open VSX上很难搜到但官方源很热门的插件比如GitLens。如果现在能搜到并且版本号很新说明官方源已经生效了。其次可以看扩展页面的相关扩展推荐官方源的推荐逻辑比Open VSX丰富得多能明显感觉到智能度提高。另一个辅助验证方法是看日志在code-server启动日志里搜索ExtensionGallery能看到读取到的市场地址是不是官方源的域名。如果还是Open VSX的地址多半是环境变量没传给进程检查systemd配置或你启动时的shell环境。4.4 切换到官方源之后可能遇到的小插曲换源之后有几天,我发现插件安装偶尔会卡在下载阶段,扩展包怎么都拉不下来。排除了环境变量配置错误之后,基本可以确定是服务器到官方VS Code市场服务器的网络链路不太稳定。这个问题不是单独改配置能解决的,我更建议把插件提前下载好,用离线方式安装。毕竟code-server也支持直接上传.vsix文件安装。操作方法是把需要的VSIX包下载到服务器上,然后在扩展面板右上角的...菜单里选择Install from VSIX,或者用命令行:code-server --install-extension ./path/to/extension.vsix离线安装的优点是不用担心网络抖动导致半途而废,而且安装速度通常更快。插件版本方面,建议优先选和本地VS Code相同或相近的版本,避免依赖差异引起兼容问题。5. C/C插件不可用问题的完整排查链路从报错到彻底解决5.1 现象描述装了插件但代码始终没有智能补全我最初在code-server里写一个C项目,装了微软官方的C/C扩展(插件ID是ms-vscode.cpptools)。扩展面板显示已安装,状态列也是正常的,但打开任意一个.cpp文件,红色波浪线、代码补全、跳转定义全部没有,只有最简单的语法高亮是正常的。状态栏右下角一直显示正在加载IntelliSense...或者那个小齿轮图标转个不停,点开还能看到一堆语言服务错误。最气的是,代码的编译本身没问题,用g手工编译能出二进制,但编辑器就是死活不提供智能分析。这种能编译但IDE不识别的场景,明显不是代码的问题,而是插件和后端语言服务没有正常联动。5.2 先把最基础的MIS检查清单过一遍遇到这类问题,我的习惯是先按下面的清单过一遍,防止在小细节上浪费太多时间:确认code-server的版本和C/C插件版本匹配。C/C扩展对code-server的版本要求比较苛刻,某些新版本插件需要更晚的VS Code API,如果你code-server还停留在4.x早期,插件强行装最新版可能会不健全。确认插件安装用户和code-server运行用户一致。如果你用root启动code-server,但插件是普通用户装的,插件根本加载不到。确认服务器上安装了必要的编译工具链。C/C扩展自带的语言服务需要底层编译器来解析标准库头文件,没有gcc/g或clang,它连iostream都找不到。确认项目的.vscode目录下没有历史遗留的冲突配置。如果之前配置过clangd或者别的C/C相关插件,残留设置会干扰cpptools的激活。我当时第一次排查时就是卡在编译工具链上——我安装的是最小化Ubuntu系统,服务器上压根没有build-essential。补上之后虽然IntelliSense能起来了,但又有新的问题,就是下面要说的头文件搜索路径。5.3 根本原因之一C/C扩展不知道你的编译器在哪、标准库头文件在哪C/C扩展的IntelliSense机制,需要在项目里明确告诉它三件事:编译器路径、头文件搜索路径、C标准版本。正常情况下这些信息可以从编辑器打开的文件夹自动推断,但远程环境里配置经常识别不准,尤其是项目依赖一些自定义头文件目录时。我解决的方式是手动为项目生成一份c_cpp_properties.json。用编辑器命令面板搜索C/C: Edit Configurations (JSON),会生成一个名为.vscode/c_cpp_properties.json的文件。内容大致如下:{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /usr/include, /usr/local/include, /usr/include/x86_64-linux-gnu/c/12, /usr/include/c/12 ], defines: [], compilerPath: /usr/bin/g, cStandard: c17, cppStandard: c17, intelliSenseMode: linux-gcc-x64 } ], version: 4 }这里面的includePath非常关键。你不需要把所有头文件路径都手工写完整,但至少要确保常见系统的头文件目录在里面。我建议在服务器终端执行:echo | g -E -x c -v - 21 | grep ^ /这一串命令会把g查找头文件的完整路径列出来,里面有/usr/include/c/12、/usr/include/x86_64-linux-gnu等一系列目录。把输出里的路径尽量补到includePath数组里,IntelliSense的红色波浪线基本就能消掉一大半。如果你的项目引入了第三方库,比如boost、OpenCV、grpc这些,擅自改全局includePath并不是好主意,更合理的做法是用compile_commands.json或者CMake的插件去驱动。这里我们先把最简单方案搞定再说。5.4 根本原因之二插件版本和code-server底层Node版本不兼容除了配置文件问题,C/C扩展还有一个非常隐蔽的坑:它内置的语言服务对Node/Nodene版本很敏感。code-server本身是Node服务,插件运行在Node环境里,而cpptools的native模块需要匹配的Node ABI版本。如果你code-server升级到了新版本,而插件市场里的cpptools还是按旧Node版本编译的,启动时会报NODE_MODULE_VERSION不匹配一类的错误。遇到这种情况,解决办法通常是升级插件到最新版本,或者回退到上一个稳定版本。打开扩展面板,找到C/C扩展,右键选择Install Specific Version,我试过最稳的一个组合是code-server 4.x C/C v1.18.x,这个组合在多个环境里跑都没问题。如果官方源主版本已经更新到2.x,也不要害怕,可以先装最新版试一下,如果报错就装回1.x老版本,两者都有支持。5.5 我后来改用clangd的替代方案以及为什么现在还留着它在cpptools折腾了不小时间之后,我也尝试了另一个方案:换成clangd插件。clangd是Clang项目自带的C/C语言服务器,补全快、响应快,深度集成compile_commands.json。如果你项目本身就是用CMake或者Makefile管理,那么clangd可以读取编译数据库,智能补全的准确度高到能当作真香来形容。安装clangd插件之前,先确保服务器上装了clangd:sudo apt install clangd然后通过扩展面板安装llvm-vs-code-extensions.vscode-clangd。首次启动插件会提示你选择clangd二进制路径,用which clangd找到后填进去即可。如果项目没有自动生成compile_commands.json,可以借助Bear工具:bear -- make生成该文件后,clangd就知道每个源文件的编译参数。这一步完成之后,我再去仓库里跑代码,跳转精度、自动补全响应速度都比原来cpptools好不少。所以我的建议是:如果遇到C/C插件不可用,先试本文提到的cpptools配置调整,如果依旧不行,直接换clangd,不要再纠结。5.6 C/C问题的其他常见诱因权限、缓存、和远程环境隔离除了上面几条,我还遇到过一个特别像玄学的问题:cpptools的缓存损坏。现象是插件能激活,但是IntelliSense一直转圈,偶尔能出结果,过一会儿又消失。后来我发现它的状态缓存放在~/.cache/cpptools目录下,删除后重启code-server就恢复了。所以如果你前面的配置都没问题,不妨试试:rm -rf ~/.cache/cpptools另外注意,code-server远程环境里,编译器和头文件路径都是服务器上的,不是本地开发机的。如果你在本地Windows上写惯了,依赖本机的SDK路径,迁到服务器上一律要重新适配。这一点也是初学者问我最多的地方。6. 部署完之后,我的性能调优和日常维护经验6.1 限制内存使用量,避免和业务进程抢资源code-server本质是Node服务,启动时如果不做特殊限制,默认最大堆内存会是系统可用内存的一半左右。在我那台4G服务器上,它一度吃掉了1.5G内存,虽然能接受,但和别的服务一起跑还是不放心。所以我在systemd服务里加了一段环境变量:EnvironmentNODE_OPTIONS--max-old-space-size2048这样Node进程的堆上限被限制在2G,配合swap空间,整体运行稳定很多。如果你的项目很大、经常加载大型工程文件,可以适当调大一点,但没必要一上来就给到4G,先看实际占用再决定。6.2 关掉遥测和更新检查,减少无谓流量在config.yaml里加上disable-telemetry: true和disable-update-check: true是我强烈建议的做法。可能在可视化界面上没什么感觉,但实际体感是启动速度略快,而且不会时不时弹出新版本可用的提示,后台也少了一些外部请求。想要进一步减少UI卡顿,还可以在code-server设置里关掉编辑器里的Workbench: Startup Editor和Window: Zoom Per Scroll Wheel这些视觉效果。6.3 数据目录的备份与迁移code-server的用户数据存储规则基本和VS Code一致,插件装在~/.local/share/code-server/extensions,用户配置在~/.local/share/code-server/User,工作区状态和最近打开的历史也都在~/.local/share/code-server里。如果你要把环境迁移到新服务器,最省事的办法是:新机器按照本文步骤装好code-server,然后把旧服务器的~/.local/share/code-server完整打包拷过去,再启动服务。我每次迁移都是先停服务再打包:sudo systemctl stop code-server tar -zcf code-server-data.tar.gz -C ~/.local/share code-server然后放到新服务器解压,再systemctl start code-server,基本上打开就是一个一模一样的开发环境。注意备份时关掉code-server,否则有些缓存文件正在写,可能会拷出半个写了一半的状态。6.4 遇到奇怪的web UI卡顿,先不要把锅甩给服务器code-server界面卡顿很多时候不是服务器配置不够,而是浏览器端的WebSocket连接不稳定。最典型的症状是编辑器能打开,但输入字符延迟明显,重连之后又正常。排查思路一般是先把Nginx反代的WebSocket超时时间调大一些,在server块里加上:proxy_read_timeout 3600s; proxy_send_timeout 3600s;或者确认你是不是开着多个浏览器tab同时连同一个code-server实例单个实例处理多个WebSocket连接时并发性能会下降这时候要么关掉多余的tab要么考虑给不同项目跑多个实例。我自己的习惯是日常开发开一个实例如果需要同时看两个项目直接开两个端口跑两个实例互相不干扰。配置上把两个实例的端口区分开就行上面提到的systemd配置可以复制一份换Name和ExecStart里参数即可。这套环境用到现在已经有几个月了中途除了换过一次证书、清理过一次插件缓存之外基本没再出过幺蛾子。如果你也打算把日常开发环境迁到code-server上建议按这个顺序来先装二进制包、配systemd、设置官方源、再把C/C扩展或者clangd调好最后性能优化和备份手段一上就能当主力环境用了。
