Ubuntu 上从零部署 Claude Code：Node.js 与 Git 环境配置避坑指南

1. 为什么值得在 Ubuntu 上认真折腾一次 Claude Code很多人第一次听说 Claude Code以为它只是个命令行版的聊天窗口装完随便敲两句就完事了。实际用下来你会发现它更像一个能读写你本地代码库、执行 shell 命令、跑测试、改配置的结对工程师。也正因为它能直接动你的文件系统部署环境是否干净、Node.js 版本是否匹配、Git 身份是否配好这些看似琐碎的前置条件直接决定了你后面是顺畅干活还是天天排错。这篇内容面向的是在 Ubuntu 上从零把 Claude Code 跑起来的人不管你是刚装完系统的纯小白还是已经用过一段时间的开发者都能从中找到能直接抄的步骤和踩坑经验。核心链路其实就四块Ubuntu 基础环境、Node.js 运行时、Git 版本管理、Claude Code 本体安装与配置。我会把每一步为什么这么做讲清楚而不是甩一堆命令让你复制粘贴。先说一个反直觉的结论大多数 Claude Code 装不上、跑不起来的问题根子不在 Claude Code 本身而在 Node.js 的版本和 PATH 环境变量上。我见过太多人卡在command not found或者模块导出报错折腾半天以为是网络问题其实是 Node 版本太老或者装了两套 Node 互相打架。所以这篇会把环境准备部分写得比官方文档更细把那些文档里默认你会、但其实新手根本不知道的环节补上。另外提醒一句Ubuntu 的版本选择也有讲究。22.04 LTS 和 24.04 LTS 是目前最稳的两个长期支持版本软件源里的 Node.js 和 Git 版本都比较新社区资料也全。如果你还在用 20.04 甚至更老的版本后面装 Node.js 时大概率要手动加源麻烦不少。有条件的话建议直接上 22.04 或 24.04。2. Ubuntu 基础环境装系统只是开始这几步不做后面全是坑2.1 系统版本与镜像选择如果你是在物理机上装去 Ubuntu 官网下载 LTS 版本的桌面版或服务器版镜像都行。桌面版带图形界面适合日常开发服务器版更轻量适合跑在云主机或者虚拟机上。如果你是用 VMware 或 VirtualBox 装虚拟机建议给至少 4GB 内存和 40GB 磁盘Claude Code 本身不重但 Node.js 生态和你的项目文件加起来会占不少空间。虚拟机安装 Ubuntu 的流程这里不展开重点说几个新手容易忽略的点。安装时如果勾选了最小安装很多常用工具比如 curl、vim不会自带后面还得手动补。我一般建议选正常安装省得后面缺东少西。另外中文输入法的问题Ubuntu 默认的 IBus 框架对中文支持一般如果你需要频繁输入中文装完系统后去设置 - 区域与语言里添加中文输入源或者直接装 Fcitx5体验会好很多。2.2 换源与系统更新装完系统第一件事把软件源换成国内镜像不然apt update能慢到你怀疑人生。以 22.04 为例编辑/etc/apt/sources.list把archive.ubuntu.com替换成清华或阿里的镜像地址。换完之后执行sudo apt update sudo apt upgrade -y这一步别偷懒。系统更新不仅带来安全补丁还会更新一些基础库后面装 Node.js 和 Git 时能少踩不少依赖冲突的坑。我遇到过有人跳过这步结果装 Node.js 时报libssl版本不匹配排查了半天。2.3 必备基础工具Ubuntu 装完有几个工具建议第一时间装上后面全程都会用到sudo apt install -y curl wget git build-essential ca-certificatesbuild-essential这个包很多人不知道为什么要装。它包含了 gcc、g、make 等编译工具某些 Node.js 原生模块比如涉及加密、数据库驱动的在安装时需要现场编译没有它就会报node-gyp相关的错误。ca-certificates则是保证 HTTPS 请求证书链正常缺了它某些下载会报证书错误。提示如果你在虚拟机里跑 Ubuntu装完系统后先确认网络能通。有时候虚拟机的网络模式选成仅主机会导致上不了网改成 NAT 或桥接模式即可。3. Node.js 安装版本选错后面全白干3.1 为什么不用 apt 直接装 Node.jsUbuntu 自带的软件源里确实有 Node.js但你apt install nodejs装出来的版本往往很老。比如 22.04 默认源里可能是 Node 12 或 14而 Claude Code 对 Node.js 版本有明确要求太老的版本会直接报错最典型的就是那个node:util does not provide an export named的报错——这基本就是 Node 版本过低导致的模块导出不兼容。所以正确做法是用 NodeSource 的官方源或者用 nvmNode Version Manager来管理。两种方式各有适用场景我下面分别说。3.2 方案一NodeSource 源安装适合只用一个版本如果你确定机器上只跑一个 Node 版本NodeSource 最省事。以 Node.js 20 LTS 为例curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完验证node -v npm -v正常应该输出v20.x.x和对应的 npm 版本。这里有个细节NodeSource 的脚本会自动帮你配置好源并导入 GPG key但如果你之前手动改过 apt 源可能会冲突。遇到报错就先sudo apt remove nodejs npm清理干净再重来。3.3 方案二nvm 安装推荐多版本切换友好我更推荐用 nvm尤其是你以后可能要在不同项目间切换 Node 版本的情况。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完关掉终端重开或者执行source ~/.bashrc让环境变量生效。然后nvm install 20 nvm use 20 nvm alias default 20nvm alias default 20这步很关键它把 20 设为默认版本不然你每次新开终端都得手动nvm use。我见过有人忘了这步结果新开一个终端 Claude Code 就找不到了还以为是安装失败。3.4 版本选择的经验之谈Claude Code 目前对 Node.js 18 及以上支持最好20 LTS 是最稳妥的选择。不建议用奇数版本如 19、21那些是过渡版本生命周期短生态兼容性也差一些。如果你机器上已经有 Node 18其实也能跑但如果遇到奇怪的模块报错第一反应就是升级到 20 试试。安装方式适用场景优点缺点NodeSource单版本、服务器环境系统级安装全局可用切换版本麻烦nvm多项目、多版本切换灵活隔离干净需要配置 shell 环境注意如果你之前用 apt 装过 Node.js一定要先彻底卸载再装新版本否则两套 Node 会打架which node指向的可能是旧的那个。4. Git 配置不只是装个软件那么简单4.1 安装与版本确认Git 在 Ubuntu 上安装很简单sudo apt install -y git git --version但装完只是第一步。Claude Code 在很多场景下会调用 Git比如查看改动、生成提交信息、对比差异。如果 Git 没配好用户身份它执行某些操作时会直接报错。4.2 全局身份配置git config --global user.name 你的名字 git config --global user.email 你的邮箱这两行是必须的。邮箱建议用你代码托管平台注册的那个这样提交记录能正确关联到你的账号。验证配置git config --global --list4.3 几个提升体验的 Git 配置除了身份还有几个配置我强烈建议一起设了git config --global init.defaultBranch main git config --global core.editor vim git config --global pull.rebase false第一行把默认分支名从master改成main跟上主流习惯。第二行设置默认编辑器Claude Code 有时会唤起编辑器让你确认信息不设的话可能弹出一个你不会用的编辑器卡住。第三行是拉取策略设成 merge 避免新手被 rebase 搞晕。4.4 SSH 密钥配置如果你要推代码到远程仓库如果你打算用 Claude Code 帮你管理远程仓库SSH 密钥得配好ssh-keygen -t ed25519 -C 你的邮箱一路回车然后把~/.ssh/id_ed25519.pub的内容复制到你的代码托管平台。测试连接ssh -T git你的平台地址看到欢迎信息就说明通了。这一步不做的话每次推送都要输密码Claude Code 自动化操作时会很别扭。5. Claude Code 本体安装与首次运行5.1 安装方式选择Claude Code 的安装方式主要有两种npm 全局安装和官方安装脚本。npm 方式最直接npm install -g anthropic-ai/claude-code如果你用 nvm 管理 Node全局包会装在当前 Node 版本对应的目录下切换版本后需要重新装。这点要心里有数。装完验证claude --version能输出版本号就说明装上了。如果报command not found八成是 npm 全局 bin 目录不在 PATH 里。用npm config get prefix看看全局目录在哪然后把它加到~/.bashrc的 PATH 里。5.2 首次启动与认证第一次运行直接敲claude它会引导你完成认证。按照提示走就行通常是在浏览器里登录账号授权。认证信息会存在本地配置目录之后就不用重复登录了。5.3 在项目目录里启动Claude Code 的设计是在哪个目录启动就作用于哪个目录。所以正确用法是先进你的项目文件夹cd ~/projects/my-app claude这样它才能读取你的项目文件、理解代码结构。如果你在 home 目录直接启动它会面对一大堆无关文件效果大打折扣。5.4 VS Code 里的配合使用如果你用 VS Code 开发可以在集成终端里直接跑 Claude Code这样代码编辑和 AI 辅助在同一个窗口里完成切换成本最低。VS Code 的集成终端默认就是 bash环境变量和系统终端一致不会出现系统终端能用、VS Code 里找不到命令的问题。如果真遇到了检查一下 VS Code 终端用的是不是 login shell。6. 那些文档不会告诉你的排错经验6.1command not found的三层排查这是最高频的问题。排查顺序应该是先which node看 Node 在不在再npm config get prefix看全局目录最后检查 PATH。大多数情况是 nvm 的环境变量没在當前 shell 生效source ~/.bashrc或者重开终端就好。6.2 模块导出报错的真相前面提到的node:util does not provide an export named这类报错本质是 Node 版本太老不支持新的模块语法。解决办法只有一个升级 Node。别去网上找什么 polyfill治标不治本。6.3 权限问题的正确处理有些人装全局包遇到权限错误第一反应是加sudo。千万别这么干。sudo npm install -g会把包装到 root 目录下后续普通用户运行时各种权限混乱。正确做法是配好 npm 的全局目录到用户目录下或者干脆用 nvm从根上避免权限问题。6.4 网络慢的应对npm 装包慢是常态可以换国内镜像npm config set registry https://registry.npmmirror.com但注意有些包在镜像上同步不及时如果装某个包报 404先换回官方源试试。常见报错根本原因解决方向command not foundPATH 未配置检查 nvm/shell 配置模块导出错误Node 版本过低升级到 20 LTS权限拒绝用了 sudo 装全局包改用 nvm 或配 prefix安装超时网络问题换镜像源7. 让 Claude Code 真正好用的几个习惯装好只是起点用顺手才是目的。第一个习惯是保持项目目录干净别在 home 目录或者一堆无关文件的目录里启动它它读取的上下文越聚焦给出的建议越准。第二个习惯是善用 Git 分支让 Claude Code 帮你改代码前先开个分支改完对比差异不满意直接丢弃这是最安全的协作方式。第三个习惯是把常用操作固化成项目里的说明文件。比如在项目根目录放一个说明文档写清楚构建命令、测试命令、代码规范Claude Code 读到之后会更懂你的项目减少来回解释的成本。这个投入一次后面每次对话都省事。最后一个经验遇到它理解偏差时别急着否定先把上下文补全。它看不到你脑子里的背景你多说一句这个函数是给定时任务用的它给出的方案可能就完全不一样了。把它当成一个刚入职但能力很强的同事沟通越清楚产出越好。环境这东西装一次顺了后面就是纯享受。Ubuntu 上跑 Claude Code 的链路并不复杂难的是那些藏在细节里的版本、路径、权限问题。把上面这些环节都过一遍你基本就能绕开九成的坑剩下的就是安心写代码了。