code-server 在 Android/Termux 上的安装、排障与进阶配置实战指南

本文基于 code-server 官方文档 docs/termux.md 展开，系统讲解如何在 Android 设备的 Termux 环境中安装并运行 code-server：包括 Termux 仓库直接安装、基于 NPM 的源码级依赖安装、版本升级流程，以及 Android 平台上最典型的两类已知问题（/sdcard 下 Git 失效、扩展安装受限）及其可行规避方案。读完后，你将能够在手机上完整跑起一个浏览器版 VS Code 实例，并配合 proot-distro 的 Linux 环境补齐 Go、Python 等开发工具链。

一、为什么选择 Termux

Android 并不是一个标准的 Linux 发行版，无法直接使用常规的安装脚本装出带完整依赖的 code-server。Termux 提供了一个免 root 的 Linux 环境（内置包管理器 pkg、独立的 $HOME 和系统路径），是 Android 上运行代码类服务的标准载体。code-server 官方文档 docs/termux.md 给出了两条安装路线：

1. Termux 仓库直接安装：最省事，pkg install code-server 一条命令搞定；
2. NPM 安装：先手动准备构建依赖（编译工具链、Node.js 等），再按 docs/npm.md 的指南执行 npm install --global code-server。

前提说明：两种方式都要求从 F-Droid 渠道获取 Termux（Play Store 版本已停止维护，缺少必要的系统权限请求）。NPM 方式对 Node.js 版本有严格要求——按 docs/npm.md 的说明，code-server 使用 Node.js 24.x，使用其他版本可能导致行为异常；而 Termux 仓库的 nodejs-lts 包恰好提供 v24，两者是匹配的。另外 docs/npm.md 明确警告：不要使用 yarn 安装 code-server，因为它不遵守 lockfile，会引入不可预期的行为。

二、方式一：通过 Termux 仓库安装（推荐）

这是文档给出的最短路径，共 4 步：

# 1. 从 F-Droid 安装 Termux 后，切换到 termux 仓库
pkg install tur-repo

# 2. 安装 code-server
pkg install code-server

# 3. 直接启动
code-server

• tur-repo 是 Termux User Repository（用户仓库），code-server 这个包就托管在其中；
• 启动后 code-server 会在首次运行时生成默认配置（见下文"命令与配置解析"一节），密码写入 ~/.config/code-server/config.yaml，浏览器访问 http://127.0.0.1:8080（本地访问）或通过手机局域网 IP 访问。

三、方式二：通过 NPM 安装

如果你需要跟随上游最新版、或需要自定义安装位置，走 NPM 路线。文档给出的完整步骤如下：

第 1 步：从 F-Droid 安装 Termux。

第 2 步：切换包源镜像。运行：

termux-change-repo

在弹出的交互界面中选择 Main Repository，将仓库切换为 Mirrors by Grimler Hosted on grimler.se（该镜像在国内及部分网络环境下更稳定）。

第 3 步：更新并升级全部包：

pkg update
pkg upgrade -y

第 4 步：安装 NPM 构建 code-server 所需的依赖：

pkg install -y \
  build-essential \
  binutils \
  pkg-config \
  python3 \
  nodejs-lts
npm config set python python3
node -v

各依赖的作用与 docs/npm.md 中 "Ubuntu, Debian" 一节的要求对应：

包	作用
build-essential	提供 C/C++ 编译工具链，用于编译 VS Code 相关的原生 Node 模块
binutils	链接器、汇编器等二进制工具
pkg-config	供原生模块构建脚本探测系统库
python3	node-gyp 构建系统依赖
nodejs-lts	Node.js 运行时，当前提供 v24，满足 code-server 对 24.x 的要求

其中 npm config set python python3 是必要的一步：node-gyp 默认寻找 python 可执行文件，而 Termux 只提供 python3，不设这条配置时原生模块编译阶段会直接失败。

第 5 步：按 docs/npm.md 的 Installing 一节执行全局安装：

npm install --global code-server

第 6 步：验证安装并启动。文档给出的启动命令是：

code-server --auth none

--auth none 表示跳过密码认证（适用于仅本地访问的手机场景）。这个参数在源码中真实存在：src/node/cli.ts 中定义了 auth 选项，其类型是 src/node/cli.ts 中的 AuthType 枚举（Password 与 None 两个取值），src/node/http.ts 中 case AuthType.None 分支会跳过登录校验逻辑。

第 7 步：后续升级已有安装：

npm update --global code-server

四、升级 code-server

docs/termux.md 的 Upgrade 一节给出的是针对独立安装（standalone release，含 tur-repo 包安装产物）的升级方式：

# 1. 删除所有旧版本目录
rm -rf ~/.local/lib/code-server-*

# 2. 重新执行官方安装脚本
curl -fsSL https://code-server.dev/install.sh | sh

这里清理 ~/.local/lib/code-server-* 目录不是任意的——install.sh 的注释与 install.sh 的实现都表明，官方安装脚本会把版本化目录 code-server-X.X.X 解压到 ~/.local/lib/ 下，并在 ~/.local/bin/ 建软链接指向当前版本。删除旧目录再重装，可以彻底避免多版本目录残留导致的版本混淆。

注意：如果你是通过 npm install --global 安装的，请改用第三节的 npm update --global code-server 升级，而不是执行 install.sh。

五、已知问题与规避方案

5.1 Git 在 /sdcard 目录下无法工作

现象：在 /sdcard（Android 共享存储）中执行 git clone、commit、stage 等操作会失败。

原因背景：Android 共享存储由 FUSE 挂载，文件系统语义与本地 Linux 文件系统不同（符号链接、文件属性、rename 等行为受限），Git 依赖的这些能力会直接踩坑。官方文档标注 Fix: None，即该问题本身无修复。

潜在规避方案（文档给出的两个方向）：

1. 从 proot-distro 的 Linux 文件系统向 /sdcard 中的目标文件夹创建软链接，让 Git 操作实际落在 Linux 文件系统上，仅通过软链接暴露给 Android；
2. 使用 Termux 自带的 git（官方推荐做法），并确保仓库目录位于 Termux 的 $HOME（Linux 文件系统）下，把 /sdcard 中的项目迁移或软链过去。

5.2 大量扩展（含语言包）安装失败

现象：在 Android 上，code-server 拒绝从市场下载大部分扩展，语言包等同样失败。

原因：Android 不会被识别为 Linux 环境，而是被视为一个单独的、不受支持的平台。此时 code-server 的行为模式相当于"Web 环境"——只允许 Web Extensions，拒绝下载需要在服务器端（Node 环境）运行的扩展。官方标注 Fix: None，但提供两条可行的规避路线（二选一）：

方案 A：手动安装 VSIX

手动下载扩展的 .vsix 文件，然后通过命令面板执行 Extensions: Install from VSIX... 命令安装。适合只装少量扩展的场景。

方案 B：伪装平台为 Linux（功能上更完整）

创建一个 JS 脚本，在启动前通过 --require 注入，重写 process.platform：

// android-as-linux.js
Object.defineProperty(process, "platform", {
  get() {
    return "linux"
  },
})

然后在启动 code-server 前用 Node 的 --require 选项确保该脚本先加载：

NODE_OPTIONS="--require /path/to/android-as-linux.js" code-server

⚠️ 风险说明（官方原文警示）：Android 与 Linux 并非 100% 兼容，此方案需自行承担风险。带有非 Node 原生依赖、或直接与操作系统交互的扩展可能出现异常。从源码结构看，扩展安装流程中的平台判断发生在 Node 进程内部，因此改写 process.platform 能绕过平台检查，但原生模块（.node 文件）的二进制兼容性不在该绕过的覆盖范围内——这正是官方提示风险的根源。

六、进阶配置与工具链

6.1 键盘快捷键与 Tab 键

Android 软键盘下 Tab 键不可用、快捷键分发异常是常见痛点。解决方案是向 code-server（VS Code 内核）的 settings.json 中加入：

{
  "keyboard.dispatch": "keyCode"
}

keyboard.dispatch 是 VS Code 的键位分发策略设置，切换为 keyCode 模式后，编辑器按键事件走物理键码通道，能正确响应 Tab 键与组合键快捷键。

6.2 在 proot-distro 中创建新用户

以下操作适用于 proot-distro 起的 Debian 环境（文档中"start Debian again"等表述均指向该环境）：

1. 创建用户：

   useradd <username> -m
   

2. 设置密码：

   passwd <username>
   

3. 授予 sudo 权限：运行 visudo，滚动到 User privilege specification 段落，在 root 行之后添加：

   username ALL=(ALL:ALL) ALL
   

4. 用命令行编辑器修改 /etc/passwd，找到该用户的行，将行末的 /bin/sh 改为 /bin/bash；

5. 切换用户：

   su - <username>
   

   注意 su 与用户名之间的 - 不可省略：它会触发执行 /etc/profile。由于 /etc/profile 中可能包含后续步骤必须生效的环境初始化（PATH、pyenv 初始化等），切换用户时应始终带上 -。

6.3 在 Debian 环境中安装 Go

以下命令需在 proot-distro 的 Debian 环境中执行。

1. 前往 golang.org 官方下载页，复制 linux arm 架构的下载链接（Termux/Debian-on-Android 通常为 32 位 ARM 或按发行版架构选择），执行：

   wget download_link
   

2. 解压安装。注意该步骤会清除之前所有 Go 安装，如有需要请先备份：

   rm -rf /usr/local/go && tar -C /usr/local -xzf archive_name
   

3. 编辑 /etc/profile，追加 PATH：

   export PATH=$PATH:/usr/local/go/bin
   

4. 运行 exit 退出（若未切换过用户，可能需要多次 exit 回到正常的 Termux shell），然后重新启动 Debian；

5. 验证安装：

   go version
   

6.4 在 Debian 环境中安装 Python（pyenv 方式）

以下命令以 root 身份执行。

第 1 步：安装 Python 编译所需依赖：

sudo apt-get update
sudo apt-get install make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

第 2 步：通过 pyenv 官方安装脚本安装 pyenv：

curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

第 3 步：编辑 /etc/profile，追加 pyenv 初始化：

export PYENV_ROOT="/root/.pyenv"
export PATH="/root/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv virtualenv-init -)"

第 4 步：退出并重启 Debian。

第 5 步：列出可安装的版本：

pyenv versions

第 6 步：安装目标版本：

pyenv install version

编译过程可能耗时较长，视设备性能约 1～2 小时。

第 7 步：设置全局版本文件：

touch /root/.pyenv/version && echo "your_version_here" > /root/.pyenv/version

第 8 步：（可能需要再重启一次 Debian）验证 PATH 是否生效：

python3 -V

如果 python3 不可用但第 6 步显示安装成功，可直接调用 pyenv 安装的绝对路径验证：$PYENV_ROOT/versions/your_version/bin/python3。

七、命令与配置解析：启动后发生了什么

前面反复出现的 code-server --auth none 值得从源码层面理解一次。code-server 的 CLI 参数定义集中在 src/node/cli.ts：

• --auth：src/node/cli.ts 定义为 auth: { type: AuthType, description: "The type of authentication to use." }，取值来自 AuthType 枚举（password / none，见 src/node/cli.ts）。设为 none 后，src/node/http.ts 中的认证分支会被跳过，浏览器直连工作区——在手机上本地回环访问时是合理选择，但若通过局域网暴露，务必使用默认的 password 模式或置于反代之后。

• --bind-addr：src/node/cli.ts 中描述为 "Address to bind to in host:port. You can also use $PORT to override the port."。在手机上若要被同网段的其他设备访问，需要绑定 0.0.0.0:8080（默认绑定是回环地址，见下一条）。

• 默认配置：首次启动时，若不存在配置文件，code-server 会写入默认配置——src/node/cli.ts 的 defaultConfigFile() 返回的内容为：

  bind-addr: 127.0.0.1:8080
  auth: password
  password: <生成的随机密码>
  cert: false
  

  即默认只监听本机回环、开启密码认证。这与"手机上默认只有本机浏览器可访问"的实际表现一致；要远程访问，修改 ~/.config/code-server/config.yaml 中的 bind-addr 即可，CLI 参数与配置键一一对应（config 选项描述见 src/node/cli.ts："Every flag maps directly to a key in the config file"）。

八、小结

在 Android 上运行 code-server 的核心思路可以归纳为：

1. Termux 是运行载体：tur-repo 包安装是最简路径；NPM 安装则要求先备好 build-essential 等编译依赖与 Node.js 24.x；
2. 升级走对应安装渠道：独立安装清理 ~/.local/lib/code-server-* 后重跑 install.sh；NPM 安装用 npm update --global code-server；
3. 两大已知问题都有绕过路径：/sdcard 下的 Git 问题用 Termux 自带 git 解决；扩展安装受限问题可用 VSIX 手动安装或 NODE_OPTIONS="--require ..." 平台伪装解决（自担原生兼容风险）；
4. 移动端体验与工具链：keyboard.dispatch: "keyCode" 修复 Tab 键；proot-distro 的 Debian 环境可完整补齐 Go、Python(pyenv) 等开发工具链，配合 su - 切换用户与 /etc/profile 初始化。

本文全部内容以当前仓库的 docs/termux.md 为主体，docs/npm.md、install.sh、src/node/cli.ts 与 src/node/http.ts 作为实现佐证，可据此继续深入对应文件。