1. 为什么要在鸿蒙 PC 上折腾 Claude Code先说清楚一件事鸿蒙 PC 版目前还处在逐步放量的阶段能拿到设备或者能刷上开源鸿蒙 PC 版的开发者基本都属于愿意吃第一口螃蟹的人。而 Claude Code 作为终端里的 AI 编程助手本身对运行环境的要求并不算离谱——一个能跑 Node.js 或 Bun 的类 Unix 环境加上网络能通到模型服务端它就能干活。问题恰恰出在“类 Unix 环境”这几个字上鸿蒙的底层虽然是 Linux 内核衍生但用户态的工具链、包管理器、动态库路径跟主流发行版差异不小直接照搬 Ubuntu 上的安装脚本十有八九会卡在某个依赖上。这篇内容就是把我自己在鸿蒙 PC 上把 Claude Code 跑起来的过程完整拆一遍重点放在最新的 Bun 版本路线上。为什么强调 Bun因为 Claude Code 早期主要靠 Node.js 驱动但 Node 在鸿蒙这种非标准环境下原生模块编译经常出问题而 Bun 是单二进制分发、自带运行时和包管理对系统依赖少得多移植成本明显更低。如果你手上正好有鸿蒙 PC 设备或者在做开源鸿蒙的桌面适配又或者单纯想搞清楚“一个为 macOS/Linux 写的 CLI 工具怎么搬到鸿蒙上”这篇应该能帮你省下不少试错时间。需要提前说明的是下面涉及的具体命令和路径是基于我在手头设备上的实测记录整理的不同鸿蒙 PC 版本比如 5.x 和 6.x在细节上可能有出入但整体思路是通用的。另外文中不会涉及任何网络访问工具的内容所有操作都假设你处在正常的网络环境下。2. 环境准备与前置条件确认2.1 确认你的鸿蒙 PC 到底能跑什么动手之前先别急着敲命令。鸿蒙 PC 和手机端的鸿蒙不是一回事PC 版保留了更完整的桌面环境和终端能力但不同版本开放的程度不一样。你需要先确认三件事终端能不能正常用、有没有包管理能力、CPU 架构是什么。打开终端先跑这几条uname -a cat /etc/os-release echo $SHELLuname -a看内核版本和架构鸿蒙 PC 目前主流是 ARM64aarch64少数开发板可能是 x86_64。这个信息决定了你后面下载 Bun 时要选哪个架构的二进制包选错了直接报“无法执行二进制文件”。/etc/os-release能看出系统标识有些鸿蒙 PC 会显示类似 OpenHarmony 的字段。$SHELL确认当前用的是 bash 还是别的后面写环境变量要用到。注意如果你的终端里uname返回的架构是aarch64那所有 x86_64 的预编译包都不能用必须找 ARM64 版本。这是新手最容易踩的第一个坑。2.2 检查基础依赖是否齐全Claude Code 运行起来需要几个基础能力解压工具、网络请求能力、以及一个可写的用户目录。逐条检查which curl wget tar unzip ls -ld ~ df -h ~curl或wget至少要有一个用来下载 Bun 的安装包。tar和unzip用于解压。df -h ~看用户目录剩余空间Claude Code 加上 Bun 运行时预留 500MB 以上比较稳妥因为后续还会缓存一些依赖和会话数据。如果发现某个工具缺失鸿蒙 PC 上通常可以用系统自带的包管理命令安装。具体命令因版本而异常见的是ohpm鸿蒙的包管理器或者系统预置的apt兼容层。这里我不写死命令因为不同发行版差异太大你可以先用which确认缺什么补什么。2.3 目录规划别把东西乱丢我习惯把这类第三方工具统一放在用户目录下的一个固定位置方便管理和清理。建议这样规划mkdir -p ~/tools/bun mkdir -p ~/.claude~/tools/bun放 Bun 运行时~/.claude是 Claude Code 默认读取配置和缓存的地方。提前建好目录后面配置环境变量时路径清晰出问题也好排查。很多人装完发现命令找不到就是因为二进制文件丢在临时目录里PATH 没配。3. Bun 版本路线的核心优势与选型逻辑3.1 为什么不用 Node.js 而选 BunClaude Code 官方早期文档里Node.js 是默认运行时。但在鸿蒙 PC 上Node.js 有几个绕不开的麻烦。第一Node 的官方预编译包对 glibc 版本有要求鸿蒙用的 C 库版本可能对不上跑起来会报GLIBC_2.xx not found。第二Node 的原生模块native addon需要现场编译而鸿蒙上不一定有完整的编译工具链node-gyp一跑就卡住。第三Node 的安装方式通常是包管理器或者 nvm 脚本这些脚本在鸿蒙上未必能正常执行。Bun 的设计思路完全不同。它是单个可执行文件内置了 JavaScript 运行时、包管理器、打包器不依赖系统的 Node 环境。官方发布的二进制包直接对应具体架构下载解压就能用没有编译环节。对于鸿蒙这种“非标准 Linux 桌面”来说这种零依赖的分发方式简直是量身定做。3.2 Bun 在鸿蒙上的兼容性实测我在 ARM64 的鸿蒙 PC 上实测Bun 的 Linux ARM64 版本可以直接运行基础的 JS 执行、文件读写、网络请求都正常。唯一需要注意的是Bun 某些依赖系统调用的高级特性比如某些性能剖析功能可能不可用但 Claude Code 用不到这些所以不影响。选版本的时候去 Bun 的官方发布页找bun-linux-aarch64.zip这个包。别选bun-linux-x64那是给 x86 机器的。下载下来解压里面就是一个bun可执行文件没有其他乱七八糟的东西。3.3 版本选择的取舍Bun 更新很频繁但我不建议无脑追最新版。Claude Code 对 Bun 的版本有一定要求太老的 Bun 可能缺少某些 API太新的又可能引入未测试的变更。我的做法是选一个近三个月内的稳定版本比如 1.1.x 系列既能满足 Claude Code 的需求又经过了足够多的社区验证。具体怎么判断下载页面会有 release notes看有没有标注 “stable” 或者被大量项目采用的版本号。如果你实在拿不准就选 Claude Code 官方文档里提到的最低支持版本往上浮一两个小版本这样最稳。4. 完整实操流程从零把 Claude Code 跑起来4.1 下载并部署 Bun 运行时假设你已经确认了架构是 aarch64在终端里执行cd ~/tools/bun curl -L -o bun.zip https://github.com/oven-sh/bun/releases/download/bun-v1.1.38/bun-linux-aarch64.zip unzip bun.zip解压后会得到一个bun-linux-aarch64目录里面的bun就是可执行文件。把它移到你规划好的位置mv bun-linux-aarch64/bun ~/tools/bun/bun chmod x ~/tools/bun/bunchmod x这步不能省否则会提示权限不足。做完之后验证一下~/tools/bun/bun --version能打印出版本号说明 Bun 本身没问题了。如果报错大概率是架构选错了回去检查uname -m的输出。4.2 配置环境变量让全局可用每次都敲完整路径太累把 Bun 加到 PATH 里。编辑你的 shell 配置文件bash 用户是~/.bashrczsh 用户是~/.zshrcecho export BUN_INSTALL$HOME/tools/bun ~/.bashrc echo export PATH$BUN_INSTALL:$PATH ~/.bashrc source ~/.bashrc配完之后直接敲bun --version应该就能用了。这里设BUN_INSTALL是有讲究的Bun 在安装全局包时会参考这个变量决定装到哪里提前设好能避免它往系统目录里乱写。4.3 安装 Claude CodeClaude Code 通过 npm 包的形式分发但既然我们有了 Bun就用 Bun 来装bun install -g anthropic-ai/claude-code这条命令会从 npm 仓库拉取 Claude Code 的包装到 Bun 的全局目录下。装完之后claude命令应该就能在终端里直接调用了。如果提示找不到命令检查一下 Bun 的全局 bin 目录有没有在 PATH 里通常是~/.bun/bin或者$BUN_INSTALL/bin。提示安装过程中如果卡在某个包下载不动多半是网络问题。可以多试几次或者换个时间段。不要轻易改 npm 源除非你清楚自己在做什么。4.4 首次启动与配置第一次运行claude它会引导你做初始配置主要是设置 API 相关的信息。这里我不展开具体怎么填因为每个人的使用方式不同。重点说几个配置文件的细节Claude Code 的配置默认放在~/.claude目录下核心文件是settings.json。你可以手动编辑这个文件来调整行为比如指定默认模型、设置超时时间等。一个比较实用的配置是调整会话数据的存储位置避免占满用户目录{ dataDir: /home/yourname/.claude/data, maxTokens: 8192 }dataDir指向一个你确定有足够空间的位置。maxTokens根据你的实际需求调设太大可能影响响应速度。4.5 验证安装是否成功跑一个最简单的测试确认 Claude Code 能正常响应claude --version claude print hello第一条看版本第二条看它能不能真的执行指令。如果第二条能返回结果说明整条链路是通的。如果卡住或者报网络错误往下看排查部分。5. 常见问题与排查技巧实录5.1 命令找不到或权限被拒这是最高频的问题。表现是敲claude提示command not found或者敲bun提示Permission denied。前者检查 PATH后者检查文件权限。排查顺序echo $PATH看 Bun 目录在不在里面ls -l ~/tools/bun/bun看有没有x权限which claude看系统能不能定位到命令如果 PATH 配了但还是找不到可能是 shell 配置文件没生效重新开一个终端窗口试试。5.2 运行时报动态库缺失错误信息类似error while loading shared libraries: libxxx.so.x: cannot open shared object file。这说明 Bun 依赖的某个系统库在鸿蒙上不存在或者版本不对。解决办法分两步先用ldd ~/tools/bun/bun看它依赖哪些库然后逐个确认这些库在系统里有没有。缺哪个就找对应的 ARM64 版本补上。鸿蒙 PC 上有些库可能藏在非标准路径可以用find / -name libxxx* 2/dev/null搜一下。注意不要随便从网上下载来路不明的 .so 文件往系统目录里塞这可能导致系统不稳定。优先用系统自带的包管理器安装。5.3 网络请求超时或失败Claude Code 需要访问模型服务端如果网络不通会报超时或者连接被拒。先确认基础网络curl -I https://www.example.com如果这条都通不了那是系统网络配置的问题跟 Claude Code 无关。如果这条通但 Claude Code 还是连不上检查它的配置里 API 地址有没有写错以及有没有设置代理相关的环境变量如果你不需要代理确保http_proxy这类变量是空的。5.4 会话数据把磁盘写满长时间使用后~/.claude目录可能积累大量会话记录和缓存。定期清理是个好习惯du -sh ~/.claude如果发现占用过大可以删掉data目录下的旧会话文件或者直接在settings.json里把dataDir指到一个大容量分区。5.5 常见问题速查表问题现象可能原因排查动作command not foundPATH 未配置检查$PATH和 shell 配置文件Permission denied文件无执行权限chmod x对应文件动态库缺失系统库版本不匹配ldd查看依赖补齐缺失库网络超时网络不通或配置错误先用curl测基础连通性磁盘占满会话数据堆积清理~/.claude/data或迁移目录启动即崩溃Bun 架构选错确认uname -m与下载包一致6. 实操心得与进阶建议6.1 把 Bun 和 Claude Code 做成可迁移的目录如果你有多台鸿蒙设备或者经常重装系统可以把~/tools/bun和~/.claude整体打包。换机器时解压到相同路径配好 PATH基本就能直接用。这比重新走一遍安装流程快得多。我自己的做法是定期把这两个目录同步到移动硬盘省得每次环境重建都从头折腾。6.2 关注 Bun 的更新节奏Bun 的迭代速度很快新版本可能修复了鸿蒙相关的兼容性问题。建议每隔一两个月去发布页看一眼如果有明确提到 Linux ARM64 的改进可以考虑升级。升级方式很简单下载新的二进制文件替换掉旧的bun然后重新跑一遍bun install -g anthropic-ai/claude-code确保依赖也是新的。6.3 用脚本固化安装流程手动敲命令容易漏步骤我后来写了个简单的 shell 脚本把下载、解压、配置 PATH、安装 Claude Code 串起来。这样在新设备上只需要跑一次脚本。脚本的核心逻辑就是本文第 4 节的步骤你可以根据自己的路径习惯调整。关键是要加错误检查比如下载失败就退出避免后续步骤在错误的基础上继续跑。6.4 关于模型接入的灵活配置Claude Code 支持接入不同的模型服务端包括本地运行的模型。如果你在鸿蒙 PC 上同时跑了本地推理服务可以在settings.json里把 API 地址指向本地端口。这样做的好处是响应快、不依赖外网缺点是本地模型的上下文长度和推理质量可能不如云端。具体怎么选看你的实际场景。配置的时候注意端口别跟系统其他服务冲突改完配置重启 Claude Code 生效。6.5 终端体验的微调鸿蒙 PC 自带的终端在字体渲染和快捷键上可能跟主流桌面环境有差异。如果觉得用着别扭可以试试装一个第三方的终端模拟器或者调整终端的配色和字体设置。Claude Code 的输出有大量代码块和颜色标记终端支持真彩色的话阅读体验会好很多。这个属于锦上添花不影响功能但用起来舒服不少。我在实际使用中最大的体会是鸿蒙 PC 上跑这类工具难点从来不在工具本身而在环境适配。Bun 之所以能跑通核心就是它把“环境依赖”这件事降到了最低。只要架构对、权限对、PATH 对剩下的就是水到渠成。如果你卡在某一步优先回头检查这三个“对”八成问题都出在这里。