1. 为什么要在手机上跑 AI 编程助手

1.1 一个真实的使用场景

先说清楚这件事到底解决什么问题。我平时主力开发机是一台笔记本，但很多时候人不在工位上——通勤路上、咖啡馆排队、甚至躺在床上突然想到一个 bug 的修法。这时候掏出手机，打开一个终端，直接让 AI 编程助手帮我改代码、跑测试、提交 commit，这个体验一旦用过就回不去了。

Claude Code 是 Anthropic 推出的命令行 AI 编程工具，它不是一个聊天窗口，而是一个能读写文件、执行命令、理解整个项目结构的 agent。传统用法是在电脑上装 Node.js，然后npm install -g全局安装。但手机能不能跑？答案是能，而且比想象中顺畅。核心思路就是用Termux这个 Android 上的终端模拟器，搭一个接近 Linux 的环境，然后在里面装 Node.js 和 Claude Code。

Termux 不是普通的终端 App，它自带包管理器pkg（本质是 apt 的封装），可以安装 Python、Node.js、Git、GCC 等一大堆工具。它运行在 Android 的沙盒里，不需要 root，也不需要刷机。这一点很关键——很多人以为要在手机上搞开发必须 root，其实 Termux 完全在用户空间运行，权限模型跟普通 App 一样。

1.2 适合谁，不适合谁

这套方案适合几类人：一是经常在外面跑、需要随时处理代码的开发者；二是想利用碎片时间学习编程的初学者，手机随身带，打开就能练；三是想体验 AI 编程助手但手头没有合适电脑的人。

不适合的情况也要说清楚：如果你要做大型项目的完整构建、跑 Android Studio 那种重型 IDE，手机体验会很差，屏幕小、内存有限、编译慢。这套方案定位是轻量级代码编辑、脚本编写、AI 辅助调试和小项目维护，不是替代主力开发机。

1.3 整体技术栈概览

整个方案的技术栈其实很清晰：

理解这个分层很重要，因为后面排查问题时，你要能快速定位是哪一层出了毛病。比如命令找不到，多半是 PATH 问题；安装失败，多半是 Node 版本或网络问题。

2. Termux 环境搭建的完整流程

2.1 安装 Termux 的正确姿势

这一步有个大坑：不要从应用商店装 Termux。Google Play 上的版本早就停止更新了，API 级别老旧，很多包装不上。正确做法是从 F-Droid 或者 GitHub Releases 下载最新版 APK。

为什么这么强调？因为 Termux 的包仓库跟 App 版本是绑定的。老版本 App 对应的仓库源可能已经失效，你pkg install的时候会各种报错，然后你会以为是网络问题，折腾半天。我踩过这个坑，换了新版 APK 之后一切正常。

安装完成后第一次打开，先做两件事：更新包列表和升级已有包。

pkg update && pkg upgrade -y

这个命令会拉取最新的包索引并升级。第一次执行时间会比较长，耐心等。中途如果问你配置文件要不要覆盖，一般选默认（保持当前版本）就行，除非你确定要重置。

2.2 换源加速：国内用户的必做项

Termux 默认的源在国外，国内下载速度可能很慢甚至超时。换成清华源是标准操作。Termux 的源配置在$PREFIX/etc/apt/sources.list，但更推荐用termux-change-repo这个交互式命令：

termux-change-repo

运行后会弹出界面，选择Mirror group，然后选Tsinghua或者Mirrors by Tsinghua。确认后它会自动改写源地址。这个方式比手动编辑文件安全，因为它会同时处理主仓库和科学计算仓库。

换完源记得再跑一次pkg update，让新源生效。实测下来，换源后下载速度能从几十 KB/s 提升到几 MB/s，装 Node.js 这种大包差别非常明显。

注意：换源后如果出现 GPG 签名错误，通常是源同步延迟导致的，等几分钟重试，或者换回官方源更新一次再换回来。

2.3 基础工具链准备

在装 Node.js 之前，先把一些基础工具装上，后面会用到：

pkg install -y git openssh ripgrep nano

逐个说下用途。git是版本控制，Claude Code 很多操作依赖它来理解项目变更；openssh提供 ssh 客户端，方便你连远程仓库；ripgrep（命令是rg）是超快的文本搜索工具，Claude Code 内部会用它来检索代码；nano是个轻量编辑器，改配置文件够用了。

这里有个经验：Termux 里装包尽量一次性把相关的都装上，因为每次pkg install都要重新解析依赖，分开装浪费时间。而且有些包之间有隐式依赖，一起装能避免版本冲突。

2.4 存储权限配置

Termux 默认只能访问自己的私有目录，访问手机共享存储需要授权。运行：

termux-setup-storage

系统会弹出权限请求，允许后 Termux 会在家目录下创建一个storage软链接，指向/storage/emulated/0，也就是手机的内部存储根目录。这样你就能用~/storage/shared访问相册、下载等公共目录了。

为什么要配这个？因为你的代码项目很可能放在手机存储里，而不是 Termux 私有目录。配好之后，cd ~/storage/shared/Projects就能进你的项目文件夹。不过要注意，共享存储的读写性能比私有目录差一些，而且某些操作（比如改文件权限）在共享存储上不生效，这是 Android 的存储沙盒机制决定的。

3. Node.js 与 Claude Code 的安装实战

3.1 Node.js 版本选择与安装

Claude Code 要求 Node.js 18 以上，官方推荐 20 LTS。Termux 仓库里的 Node.js 版本通常比较新，直接装就行：

pkg install -y nodejs

装完验证：

node -v npm -v

如果显示v20.x.x或更高，就没问题。如果版本太低，可以考虑用nvm管理多版本，但在 Termux 上 nvm 偶尔会有兼容问题，能用系统包就用系统包。

这里解释下为什么版本这么重要。Claude Code 用了不少较新的 JavaScript 特性，比如顶层 await、新的模块解析逻辑。Node 18 以下可能直接报语法错误。而且 npm 的版本也跟 Node 绑定，老 Node 带的 npm 装包时可能不认某些 package.json 字段。

3.2 安装 Claude Code

官方推荐全局安装：

npm install -g @anthropic-ai/claude-code

这条命令会从 npm 仓库拉取最新版并装到全局。Termux 的全局路径是$PREFIX/lib/node_modules，可执行文件软链到$PREFIX/bin，这个目录默认在 PATH 里，所以装完直接能调用。

安装过程可能遇到几个问题。一是网络慢导致超时，可以配 npm 镜像：

npm config set registry https://registry.npmmirror.com

二是权限问题，Termux 一般不会遇到，因为$PREFIX目录用户可写。三是磁盘空间不足，Node 全局包加上依赖可能占几百 MB，手机存储紧张的话要先清理。

装完验证：

claude --version

能输出版本号就成功了。

3.3 首次启动与登录

第一次运行claude，它会引导你完成认证。这个过程需要浏览器或者 API key。在手机上，浏览器跳转可能不太顺畅，所以更推荐用 API key 方式。

设置环境变量：

export ANTHROPIC_API_KEY="你的key"

想持久化就写进~/.bashrc或~/.zshrc。然后claude启动后会自动读取。

提示：API key 属于敏感信息，不要提交到 git 仓库，也不要在公共场合截图分享。建议单独放在一个不纳入版本控制的配置文件里，用source加载。

3.4 目录结构与工作区规划

建议在 Termux 里规划一个清晰的工作区，比如：

~/projects/ # 放你的代码项目 ~/projects/scripts/ # 放临时脚本 ~/storage/shared/ # 手机共享存储

Claude Code 的工作方式是"在某个目录下启动，它就以该目录为项目根"。所以启动前先cd到项目目录，它才能正确理解上下文。如果你在~下直接启动，它会把整个家目录当项目，检索范围太大，响应变慢。

4. 实际使用中的关键技巧与配置

4.1 让 Claude Code 理解你的项目

Claude Code 启动后会自动扫描项目结构，但它不是万能的。你可以在项目根目录放一个CLAUDE.md文件，写明项目说明、技术栈、代码规范、常用命令。它每次启动会读这个文件，相当于给 AI 一份项目说明书。

我一般会写这几块内容：项目是干什么的、目录结构说明、怎么跑测试、代码风格要求、有哪些坑不能踩。写清楚之后，AI 生成的代码质量明显提升，因为它知道你的约定，不会乱用你没装的库。

4.2 手机上的交互优化

手机屏幕小，Claude Code 的输出如果很长，翻起来很累。几个实用技巧：

一是用claude -p "你的问题"这种一次性模式，输出完就退出，适合快速问答。二是把常用操作写成 shell 别名，比如：

alias cc='claude' alias ccp='claude -p'

三是善用 Termux 的额外按键栏，可以自定义快捷键，把 Ctrl、Esc、方向键放上去，操作效率提升很多。在 Termux 设置里可以配置 extra keys。

4.3 与 Git 工作流配合

Claude Code 能直接执行 git 命令，这是它比普通聊天 AI 强的地方。典型流程是：让它改代码，然后让它git diff看改动，确认没问题再git commit。

但要注意，不要让 AI 自动 push。手机上误操作的风险高，push 之前一定要自己 review 一遍。我的习惯是让 AI 只做本地 commit，push 手动执行，这样有个缓冲。

另外，Termux 里配 git 用户信息：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

不配的话 commit 会报错。

4.4 性能与资源管理

手机内存有限，Claude Code 加上 Node.js 运行时，占用可能到几百 MB。如果同时开多个 Termux 会话，容易卡顿。建议：

• 用完及时退出 claude 进程
• 不要同时跑大型编译任务
• 定期pkg clean清理缓存
• 用htop或top监控资源占用

还有个细节：Termux 默认会在后台保持会话，但 Android 系统可能杀进程。可以在通知栏把 Termux 设为"不优化电池"，减少被杀的几率。

5. 常见问题排查速查表

5.1 安装类问题

5.2 运行类问题

claude启动后无响应，先检查网络。Claude Code 需要访问 API，网络不通就会一直转圈。可以用curl测试连通性。

如果报认证错误，检查 API key 是否正确设置，有没有多余空格。环境变量在子 shell 里可能不继承，确认是在同一个会话里设置的。

输出乱码或者颜色异常，通常是终端类型问题。设置export TERM=xterm-256color一般能解决。

5.3 我踩过的几个坑

第一个坑是在共享存储里跑 npm 项目。Android 的共享存储不支持符号链接和某些文件权限操作，npm 装依赖时会失败。解决办法是把项目放在 Termux 私有目录~/projects下，需要跟手机文件交互时再拷贝。

第二个坑是后台进程被系统杀掉。跑一个长任务，切出去回个消息，回来发现进程没了。除了设置电池不优化，还可以用termux-wake-lock命令获取唤醒锁，防止 CPU 休眠。

第三个坑是npm 全局包更新后命令失效。有时候升级 Node 大版本，旧的全局包路径变了，需要重新npm install -g。升级 Node 后记得重装 Claude Code。

6. 进阶玩法与扩展思路

6.1 配合其他工具形成工作流

Termux 里可以装 Python、ffmpeg、imagemagick 等一堆工具。Claude Code 能调用这些命令行工具，等于你有了一个能写代码、能处理多媒体、能跑脚本的全能助手。比如让它写个 Python 脚本批量处理图片，然后直接执行，整个流程在手机上闭环。

6.2 远程连接开发机

如果手机性能不够跑重任务，可以用 ssh 连到远程服务器，在服务器上跑 Claude Code，手机只作为终端。这样既享受手机的便携，又用上服务器的算力。Termux 的 ssh 客户端很完善，配好密钥登录后体验跟本地差不多。

6.3 自动化脚本

把常用操作封装成脚本，比如一键拉取代码、跑测试、生成 commit message。Claude Code 支持非交互模式，可以嵌到 shell 脚本里，实现半自动化的工作流。这个方向可玩性很高，适合喜欢折腾的人。

6.4 关于打包成 APK 的思考

社区里有人尝试把 Termux 环境打包成独立 APK，让用户装上就能用，省去配置步骤。这个思路对小白友好，但维护成本高，因为 Termux 的包更新频繁，打包版本容易过时。我的建议是：自己用就老老实实配 Termux，想分享给别人再考虑打包，而且要说明清楚版本和更新方式。

我在实际使用中最大的体会是，手机跑 AI 编程助手这件事，门槛比想象中低，但细节比想象中多。真正卡住新手的往往不是技术难点，而是源没换、版本不对、权限没给这些琐碎问题。把这篇里的步骤按顺序走一遍，基本能避开大部分坑。剩下的就是多用，用熟了之后，手机真的能成为一个随时待命的开发终端。