code-server on iOS：在 iPhone/iPad 上用 iSH 跑 Web 版 VS Code 的完整实战

code-server 是一个在浏览器中运行 VS Code 的开源项目，它由 Node.js 驱动，服务端要求 Node.js 24（见 package.json 中 "engines": { "node": "24" }）。iOS 不允许直接运行 Linux 程序，因此官方文档 ios.md 给出的方案是：借助 App Store 上的 iSH（一个基于 QEMU 用户模式、运行 Alpine Linux 的 shell 应用）在 iOS 上构建一个“伪 Linux 环境”，再按 Alpine 的标准流程把 code-server 装进去。本文完整继承该文档的 7 步操作流程，并结合仓库中的 install.sh、settings.ts 等源码，深入解释每一步背后的原因与可验证的依据。

读完本文，你将能够：

1. 在 iOS 设备上从零完成 code-server 的部署（iSH + Alpine + curl/nano + Node.js + 官方安装脚本）；
2. 理解为什么必须修改 /etc/apk/repositories 把 v3.14 改成 v3.12；
3. 弄清官方安装脚本在 Alpine 环境下具体走了哪条安装分支；
4. 知道如何验证服务是否正常、默认监听地址与密码在哪里。

一、环境前提：iSH 提供的 Alpine Linux 是什么

iSH 不是普通的终端模拟器，它在 iOS 进程内以软件模拟 CPU 的方式运行 Alpine Linux 用户空间，因此其中拥有完整的 apk 包管理器和标准 Linux 目录结构（/etc/apk/、~/.config/ 等）。这解释了为什么 ios.md 全程使用 apk add 这类 Alpine 命令，而不是 apt 或 brew。

有两个与本文直接相关的事实前提：

• 软件模拟，性能有限。从源码结构看，code-server 本体是纯 Node.js 应用（install.sh 的 standalone 包“bundle the node binary and node modules”），CPU 密集操作（如大型项目索引）在 iSH 中会比原生环境慢，这是使用方式决定的固有约束。
• iSH 的 Alpine 仓库中的 Node.js 版本较旧。这正是文档中第 3 步要改仓库源的原因，详见第三节。

二、完整安装流程（与 docs/ios.md 一一对应）

以下步骤逐条继承自 ios.md，命令可原样复制执行：

步骤 1：安装 iSH

从 App Store 安装 iSH。首次启动后按提示进入 shell（默认以 root 登录）。

步骤 2：安装 curl 和 nano

apk add curl nano

• curl 是后续执行官方安装脚本 curl -fsSL https://code-server.dev/install.sh | sh 的前提；
• nano 是后续编辑 /etc/apk/repositories 用的文本编辑器。

步骤 3：把 Alpine 仓库从 v3.14 降级到 v3.12（关键步骤）

nano /etc/apk/repositories

打开后可以看到两行（或多行）形如 https://dl-cdn.alpinelinux.org/alpine/v3.14/main 的仓库地址。把每一行链接里的 v3.14 都改成 v3.12，保存退出。

这一步的原理：iSH 所维护的 Alpine 软件包集合是固定快照。在 v3.12 的仓库镜像中，nodejs 包提供的是与 code-server 当时构建兼容的 Node.js 版本；而 v3.14 仓库中的 nodejs 版本与 code-server 的依赖（尤其是需要编译的 native 模块）不匹配，按文档给出的操作执行即可保证可安装、可运行。

步骤 4：安装 Node.js 与 npm

apk add nodejs npm

此时 node 和 npm 已可用。code-server 的 npm 安装路径需要 Node.js + 能编译 native 模块的工具链，docs/npm.md 中 Alpine 一节列出的依赖（apk add alpine-sdk bash libstdc++ libc6-compat python3 krb5-dev）在 iSH 的 Alpine 环境中大多已随基础镜像具备或随 nodejs npm 间接提供；若后续安装脚本报缺少编译器之类的错误，可按 docs/npm.md 的 Alpine 小节补齐这些包。

步骤 5：运行官方安装脚本

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

仓库根目录的 install.sh 与该文档是同一份脚本，其内部逻辑可以精确解释 iSH 上会发生什么：

1. distro() 函数读取 /etc/os-release，iSH 的 Alpine 会返回 alpine；

2. 在 main() 的分发逻辑中：

   case $DISTRO in
     ...
     # We don't have GitHub releases that work on Alpine or FreeBSD so we have no
     # choice but to use npm here.
     alpine | freebsd) install_npm ;;
     ...
   esac
   

   即 Alpine 分支直接调用 install_npm()（install.sh）。这是因为 GitHub 预编译 release 只覆盖 Linux 的 amd64 与 arm64（见脚本开头 usage 注释），而 iSH 模拟的架构无法匹配任何预编译包；

3. install_npm() 最终执行 npm install -g code-server@<VERSION>，并在安装完成时打印提示：把 npm 全局 bin 目录加入 PATH，然后运行 code-server（install.sh）。

安装过程需要编译 native 模块，在 iSH 的软件模拟环境下可能持续较长时间，属于正常现象。建议保持 iSH 在后台、不要切走杀掉进程。

步骤 6：启动 code-server

code-server

从源码看，cli.ts 中默认配置模板为 bind-addr: 127.0.0.1:8080（src/node/cli.ts），即默认只监听本机回环地址、端口 8080，并首次生成密码。这与 iSH 场景正好匹配：服务跑在设备本地，浏览器也在同一台 iOS 设备上，localhost 即可互通。

步骤 7：浏览器访问

在 iOS 上打开 Safari（或任意浏览器），访问：

http://localhost:8080

若配置了密码（默认行为），输入后进入登录页即可使用完整的 Web 版 VS Code。密码文件位置见下文。

三、配置与密码：验证安装是否成功

安装并启动后，可以对照源码确认默认行为：

• 默认监听地址：127.0.0.1:8080，来源是 cli.ts 中生成初始配置时写入的 bind-addr: 127.0.0.1:8080 与 port: 8080；

• 密码位置：~/.config/code-server/config.yaml，与 docs/install.md 各安装方式末尾的统一提示一致（“Your password is in ~/.config/code-server/config.yaml”）。在 iSH 中可用 cat ~/.config/code-server/config.yaml 查看；

• 想跳过认证（仅本机访问时）：code-server --auth none，该用法与 docs/termux.md 中移动设备的启动方式相同；

• 升级：与 docs/termux.md 的 Upgrade 小节一致，先删除旧安装再重跑安装脚本：

  rm -rf ~/.local/lib/code-server-*
  curl -fsSL https://code-server.dev/install.sh | sh
  

  如果当初是通过 npm 分支安装的（iSH 的 Alpine 环境正是如此），对应的清理命令是 npm uninstall --global code-server（见 docs/install.md Uninstall 小节），之后再重新执行安装脚本。

四、常见问题与排错

1. curl: command not found

iSH 是精简 Alpine，默认不带 curl，先执行 apk add curl nano（文档步骤 2）。

2. 安装脚本卡住或长时间无输出

npm 分支要编译 native 模块，iSH 的软件模拟 CPU 使这一过程显著慢于实体机。可先按 docs/npm.md “Debugging install issues with npm” 一节的方式在终端里观察日志：

npm install --loglevel verbose --global code-server

3. 启动后浏览器访问不到

• 确认终端里 code-server 打印的 URL 是 127.0.0.1:8080 还是 localhost:8080，两者在 iSH 内都指向同一回环；
• 确认没有第二个进程占用 8080；必要时换端口启动，例如 code-server --port 3000 后访问 http://localhost:3000（--port 为 cli.ts 定义的启动参数，默认 8080）。

4. 修改仓库版本后 apk add 报签名/仓库错误

重新检查 /etc/apk/repositories，确保两行链接（main 与 community）都已统一改为 v3.12，且没有残留 v3.14；改完后先执行 apk update 刷新索引再安装。

五、小结

环节	命令/文件	依据
安装 iSH	App Store	docs/ios.md 步骤 1
基础工具	apk add curl nano	docs/ios.md 步骤 2
仓库降级	nano /etc/apk/repositories，v3.14 → v3.12（两处）	docs/ios.md 步骤 3
Node.js	apk add nodejs npm	docs/ios.md 步骤 4
安装 code-server	curl -fsSL https://code-server.dev/install.sh | sh	install.sh 的 alpine → install_npm 分支
启动	code-server	默认 127.0.0.1:8080，见 src/node/cli.ts
访问	http://localhost:8080	docs/ios.md 步骤 7

整套方案的本质是：iSH 负责提供一个足够完整的 Alpine Linux 用户空间，官方安装脚本负责在 Alpine 分支下用 npm 构建并全局安装 code-server，浏览器则通过 localhost 回环连接本地服务。只要严格按照仓库文档的 7 步执行，并保持第 3 步仓库版本修改的正确性，就能在 iPhone/iPad 上获得一个可编辑本地文件、运行终端的 Web 版 VS Code。