code-server Android 实战：使用 UserLAnd 与 Nix-on-Droid 在手机上运行 VS Code

本文基于 docs/android.md 整理并扩充，讲解如何在 Android 设备上通过 UserLAnd（Ubuntu 虚拟机）或 Nix-on-Droid（Nix 环境）两种方式部署 code-server，获得一个完整的浏览器端 VS Code 开发环境。读完你可以独立完成从系统环境准备、Node.js 版本选择到服务启动、本地访问的全部流程，并理解默认端口、配置文件与密码机制的来源，从而在手机端完成真实开发任务。

环境前提：为什么必须使用 Node.js 24

在两条部署路线里，文档都明确要求先准备 Node.js 24 再安装 code-server。这不是随意指定的版本：仓库根目录的 package.json 中通过 engines 字段声明了 "node": "24"，开发类型依赖也锁定在 @types/node: 24.x；官方 npm 安装文档 docs/npm.md 同样说明“使用 Node.js 24.x，其他版本可能导致不可预期的行为”。因此无论在 UserLAnd 还是 Nix-on-Droid 中，Node.js 大版本对齐是安装成功的首要前提。

此外还有两点通用前提（参见 docs/requirements.md）：

• 官方建议机器最低约 1 GB 内存、2 个 CPU 核心，现代手机通常满足；
• 环境必须支持 WebSocket，因为 code-server 依赖 WebSocket 在浏览器与服务端之间通信（源码中的 WebSocket 处理见 src/node/socket.ts、src/node/wsRouter.ts）。

方式一：UserLAnd（Ubuntu 虚拟机）

UserLAnd 是一个 Android 应用，可在手机上运行完整的 Ubuntu 用户空间虚拟机。code-server 文档给出的官方步骤如下，共 10 步：

1. 从 Google Play 安装 UserLAnd；
2. 在应用内安装一个 Ubuntu 虚拟机（VM）；
3. 启动应用，进入 Ubuntu 终端；
4. 安装 Node.js 与 curl：

sudo apt install nodejs npm curl -y

5. 安装 nvm（Node 版本管理器）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

6. 用 exit 退出当前终端，然后重新打开终端，使 nvm 的环境加载生效；
7. 安装并切换到 Node.js 24：

nvm install 24
nvm use 24

8. 全局安装 code-server：

npm install --global code-server

9. 运行：

code-server

10. 在浏览器中访问 localhost:8080。

这里有几个值得展开的细节：

• 为什么用 nvm 而不用 apt 装的 Node：Ubuntu 发行版源中的 Node 版本通常落后，无法满足 Node 24 的要求；通过 nvm 安装 24 后再 nvm use 24，保证 npm install --global code-server 实际运行在正确的 Node 大版本上。
• npm 全局安装装的是什么：安装后得到的 code-server 可执行命令就是 package.json 中声明的 bin 入口 out/node/entry.js；其后的服务主逻辑位于 src/node/main.ts 与 src/node/app.ts。
• 8080 端口的来源：第一次直接运行 code-server 时并没有配置文件，服务却恰好监听在 8080。这是因为 src/node/cli.ts 中的 defaultConfigFile() 会在首次启动时生成默认配置，其中就写明了 bind-addr: 127.0.0.1:8080。

方式二：Nix-on-Droid（Nix 环境）

如果你偏好 Nix 包管理，docs/android.md 提供了第二条路线：

1. 从 F-Droid 安装 Nix-on-Droid；
2. 启动应用；
3. 用一条命令拉起带 code-server 的 shell：

nix-shell -p code-server

4. 运行：

code-server

5. 在浏览器中访问 localhost:8080。

这条路线的优势在于把 Node.js 版本管理、依赖编译全部交给 Nix 解析，nix-shell -p code-server 会自动提供一个与 code-server 发布版本匹配的运行环境，避开了方式一中手工对齐 Node 版本的步骤。

启动之后：默认配置、密码与访问地址

两种方式的第最后一步都是“浏览器访问 localhost:8080”。理解其背后的机制，有助于排查启动问题：

• 默认配置文件自动生成：src/node/cli.ts 中的 readConfigFile() 在读取配置前，会尝试向 $CODE_SERVER_CONFIG 或默认的 ~/.config/code-server/config.yaml 写入一份默认配置（bind-addr: 127.0.0.1:8080、auth: password、随机生成的 password、cert: false），且只在文件不存在时写入（flag: "wx"），不会覆盖已有配置。
• 密码位置：首次启动后，登录密码打印在终端日志中，同时保存在 ~/.config/code-server/config.yaml 里——npm 安装文档（docs/npm.md）中“密码在 ~/.config/code-server/config.yaml”的说明与之完全对应。
• 监听地址的含义：默认 127.0.0.1:8080 意味着服务只绑定回环地址。在 UserLAnd / Nix-on-Droid 这类本地运行场景中，直接用同一设备的浏览器访问 localhost:8080 即可；如需跨设备访问，则需自行修改 bind-addr 并自行评估网络暴露风险。

已知限制与补充建议

• 扩展安装限制：Android 环境在 VS Code 看来并非标准 Linux 平台，服务端运行的扩展（含语言包）可能无法直接安装，仅 Web 扩展被允许。docs/termux.md 在“Known Issues”中记录了这一现象并给出两种绕行方式：手动下载 .vsix 通过命令面板“从 VSIX 安装”，或用 --require 注入脚本把 process.platform 伪装为 linux（注意 Android 与 Linux 并非 100% 兼容，含原生依赖的扩展可能有风险）。在 UserLAnd 的完整 Ubuntu 虚拟机中，运行环境接近真实 Linux，此类限制通常不会出现。
• 备选路线：如果不想引入虚拟机或 Nix，也可以直接在 Termux 中安装 code-server，完整步骤（含已知问题与键盘、用户创建等技巧）见 docs/termux.md。
• 升级：npm 方式安装后，升级 Node 版本后可能需要重新编译原生模块（在 code-server 的 lib/vscode 目录执行 npm rebuild 或重新全局安装），参考 docs/npm.md 的 Troubleshooting 一节。

小结

路线	环境	核心命令	适用人群
UserLAnd	Ubuntu 虚拟机 + nvm + Node 24	npm install --global code-server 后 code-server	想要完整 Linux 用户空间、可扩展性最强
Nix-on-Droid	Nix 环境	nix-shell -p code-server 后 code-server	偏好 Nix、希望最少手工配置
Termux（备选）	Termux 包管理器	pkg install code-server	不想装虚拟机，接受扩展安装限制

两条官方路线的共同点是：先在手机端准备好满足 Node 24 的运行环境，再全局安装并直接运行 code-server，最后在浏览器打开 localhost:8080、使用 ~/.config/code-server/config.yaml 中记录的密码登录。掌握默认配置生成机制（src/node/cli.ts）后，你就能在此基础上按需调整绑定地址、认证方式等配置，把手机变成一个随身携带的远程开发工作站。