1. 为什么要在 Ubuntu 上折腾 Claude Code1.1 这个工具到底解决什么问题Claude Code 是 Anthropic 推出的命令行 AI 编程助手它跟你在网页上跟 AI 聊天写代码完全是两码事。网页版你得自己复制粘贴代码、自己找文件、自己执行命令而 Claude Code 直接跑在你的终端里能读取你当前项目的文件结构、理解代码上下文、直接帮你改文件、跑测试、执行 git 操作。说白了它就像一个坐在你旁边、能直接操作你电脑的编程搭档。那为什么非得在 Ubuntu 上部署三个原因。第一Ubuntu 是绝大多数后端开发和运维场景的标准环境你的代码最终跑在 Linux 服务器上本地开发环境跟生产环境保持一致能省掉大量在我机器上能跑的问题。第二Claude Code 的很多能力依赖 Unix 工具链比如grep、find、sed、awk这些在 Ubuntu 上原生支持体验比在 Windows 上顺畅得多。第三Ubuntu 的包管理、权限体系、终端环境对开发者更友好装 Node.js、配 Git、跑脚本都是一条命令的事。这篇文章适合谁看如果你刚装好 Ubuntu 系统或者用虚拟机/WSL 跑了个 Ubuntu想在上面把 Claude Code 跑起来那这篇就是写给你的。我会从系统准备一路讲到实际使用包括 Node.js 安装、Git 配置、Claude Code 安装、常见报错排查每一步都给出具体命令和背后的原因。1.2 部署前你需要知道的几件事在动手之前有几个前提条件得先确认清楚不然装到一半卡住会很痛苦。系统版本要求Ubuntu 20.04 LTS 及以上都行推荐 22.04 LTS 或 24.04 LTS。LTS 版本意味着长期支持软件源稳定不会因为系统升级导致依赖断裂。如果你用的是非 LTS 版本可能会遇到 Node.js 源不匹配的问题。网络环境Claude Code 需要访问 Anthropic 的 API 服务所以你的机器得能正常访问外网。如果你在公司内网或者有防火墙限制需要提前确认网络策略。另外 npm 安装包的时候也需要能访问 npm registry国内用户可能会遇到下载慢的问题后面我会讲怎么处理。硬件要求Claude Code 本身很轻量它只是个客户端真正的计算在云端。所以你的机器不需要 GPU不需要大内存一台普通的开发机甚至虚拟机都够用。但如果你同时跑着 Docker、数据库、IDE建议至少 8GB 内存不然终端会卡。账号准备你需要一个 Anthropic 账号并且开通了 Claude Code 的使用权限。目前 Claude Code 是付费服务需要订阅 Claude 的 Pro、Max 或者 Team 计划或者通过 API key 按量计费。这个在安装之前就得搞定不然装完了也用不了。注意不要用网上随便找的共享账号或者来路不明的 API key一是容易被封二是你的代码内容会经过别人的账号存在泄露风险。2. Ubuntu 系统基础环境准备2.1 系统更新与基础工具安装拿到一台刚装好的 Ubuntu第一件事永远是更新软件源和已安装的包。这不是形式主义而是因为很多预装的包版本太老直接装 Node.js 或者 Git 的时候会因为依赖版本冲突报错。打开终端依次执行sudo apt update sudo apt upgrade -yapt update是刷新软件源索引告诉系统现在有哪些包、什么版本可以装。apt upgrade是把已安装的包升级到最新版本。这两个命令分开执行是有原因的先 update 再 upgrade确保升级的是最新索引里的版本。加-y是自动确认省得你一个个按回车。升级完之后装几个后面一定会用到的基础工具sudo apt install -y curl wget git build-essential ca-certificates这几个包的作用分别是curl和wget用来下载文件git是版本控制工具Claude Code 很多功能依赖它build-essential包含 gcc、g、make 等编译工具有些 npm 包需要本地编译ca-certificates是 HTTPS 证书没有它 curl 访问 https 站点会报证书错误。我踩过的坑有一次在一台最小化安装的 Ubuntu 上直接装 Node.js结果 npm 装某个包的时候报gyp ERR! stack Error: not found: make就是因为没装 build-essential。所以这一步别省。2.2 检查系统架构和版本在下载任何东西之前先确认你的系统架构因为 Node.js 的安装包分 x64 和 ARM64下错了装不上。uname -m lsb_release -auname -m输出x86_64就是 64 位 Intel/AMD 架构输出aarch64就是 ARM64 架构比如树莓派或者某些云服务器。lsb_release -a会显示 Ubuntu 的版本号和代号比如22.04对应jammy24.04对应noble。记住这个代号后面配 Node.js 源的时候要用。如果你是在虚拟机里跑 Ubuntu比如 VMware 或者 VirtualBox建议给虚拟机分配至少 2 核 CPU、4GB 内存、40GB 硬盘。Claude Code 本身不重但 Ubuntu 桌面版加上浏览器、终端、编辑器资源消耗不小。如果是 WSL 环境默认配置通常够用但建议在.wslconfig里把内存限制调到 4GB 以上。2.3 配置中文环境和输入法可选但推荐如果你习惯中文界面可以装中文语言包和输入法。这一步不是必须的但如果你要在 Ubuntu 上长期开发中文输入法能省不少事。sudo apt install -y language-pack-zh-hans fonts-noto-cjk然后装输入法框架和拼音输入法sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3装完之后需要在设置 - 区域与语言 - 输入源里添加中文拼音然后重启系统生效。这里有个细节Ubuntu 22.04 之后默认用 Wayland 显示协议fcitx5 在 Wayland 下有时候会有兼容问题如果输入法不工作可以在登录界面切换到 X11 会话试试。提示如果你只是把 Ubuntu 当服务器用纯命令行操作这一步完全可以跳过。中文输入法只在图形界面下有意义。3. Node.js 环境安装与版本管理3.1 为什么 Claude Code 需要 Node.jsClaude Code 是通过 npm 分发的npm 是 Node.js 的包管理器。所以你得先有 Node.js才能用 npm 装 Claude Code。这就像你要用 pip 装 Python 包得先有 Python 一样。但这里有个版本要求Claude Code 需要 Node.js 18 或更高版本。我实测下来Node.js 18、20、22 都能正常跑但推荐用 20 LTS 或 22 LTS因为这两个是当前的长期支持版本稳定性和安全性都有保障。Node.js 18 虽然也能用但已经进入维护期了新项目不建议。为什么不直接用sudo apt install nodejs因为 Ubuntu 官方源里的 Node.js 版本通常很老。比如 Ubuntu 22.04 默认源里是 Node.js 12根本跑不了 Claude Code。所以我们需要通过 NodeSource 的源来装新版本或者用 nvm 来管理。3.2 方法一用 NodeSource 源安装推荐新手NodeSource 是一个专门提供 Node.js 二进制分发的服务它维护了各个 Ubuntu 版本对应的 apt 源。用这种方式装Node.js 会像系统包一样被管理升级方便。先安装 NodeSource 的源配置脚本。以 Node.js 20 为例curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -这行命令做了几件事curl -fsSL下载脚本-f是遇到 HTTP 错误就失败-s是静默模式-S是出错时显示错误-L是跟随重定向。sudo -E bash -是以 root 权限执行下载的脚本-E保留环境变量。脚本会自动检测你的 Ubuntu 版本然后添加对应的 apt 源和 GPG 密钥。执行完之后再装 Node.jssudo apt install -y nodejs验证安装node -v npm -v如果输出v20.x.x和10.x.x之类的版本号就说明装好了。如果node -v报command not found检查一下上一步的源配置脚本有没有报错。我遇到过的情况在某些网络环境下curl下载 NodeSource 脚本会超时。这时候可以多试几次或者换用下面的 nvm 方法。3.3 方法二用 nvm 管理多版本推荐老手nvm 是 Node Version Manager它允许你在同一台机器上装多个 Node.js 版本随时切换。如果你同时维护多个项目有的需要 Node 18有的需要 Node 22nvm 就是刚需。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后需要重新加载 shell 配置source ~/.bashrc如果用的是 zsh就source ~/.zshrc。然后验证nvm --version看到版本号就说明装好了。接着装 Node.jsnvm install 20 nvm use 20 nvm alias default 20nvm install 20装 Node.js 20 的最新版nvm use 20切换到 20nvm alias default 20把 20 设为默认版本这样新开终端自动用 20。nvm 的好处是版本切换干净不会污染系统环境。缺点是每次新开终端需要确保 nvm 被加载不过安装脚本通常会自动往.bashrc里加加载代码。3.4 npm 镜像加速配置国内网络环境下npm 默认的 registry 下载速度可能很慢装 Claude Code 的时候会卡住。可以换成国内镜像源npm config set registry https://registry.npmmirror.com验证npm config get registry如果输出https://registry.npmmirror.com就说明改好了。这个镜像源是淘宝维护的同步频率很高绝大多数包都能正常下载。注意有些公司内部有私有 npm 源如果你在公司网络里先问一下运维该用哪个源。乱改 registry 可能导致内部包拉不下来。4. Git 安装与配置4.1 Git 安装与版本确认Git 在 Claude Code 的工作流里扮演重要角色。Claude Code 会读取你的 git 仓库状态知道哪些文件被修改了、当前在哪个分支、最近的提交是什么。它还能帮你执行 git 操作比如创建分支、提交代码、查看 diff。所以 Git 必须装好而且版本不能太老。Ubuntu 上装 Git 很简单sudo apt install -y git验证git --versionUbuntu 22.04 默认源里的 Git 是 2.3424.04 是 2.43都够用。如果你需要更新的版本可以加 Git 官方的 PPAsudo add-apt-repository ppa:git-core/ppa sudo apt update sudo apt install -y git4.2 Git 全局配置装完 Git 第一件事是配置用户名和邮箱因为每次提交都会记录这些信息git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的邮箱建议跟你 GitHub/GitLab 账号的邮箱一致这样提交记录能正确关联到你的账号。接着配置几个实用的默认项git config --global init.defaultBranch main git config --global core.editor nano git config --global pull.rebase falseinit.defaultBranch main让新建仓库的默认分支叫main而不是master跟 GitHub 的默认保持一致。core.editor nano设置默认编辑器为 nano如果你习惯 vim 就改成vim。pull.rebase false让git pull默认用 merge 而不是 rebase避免新手误操作导致提交历史混乱。4.3 SSH 密钥配置连接远程仓库用如果你要把代码推到 GitHub 或者公司的 Git 服务器配 SSH 密钥比每次输密码方便得多。生成密钥ssh-keygen -t ed25519 -C 你的邮箱一路回车就行默认存在~/.ssh/id_ed25519。-t ed25519指定用 Ed25519 算法比 RSA 更短更安全。然后查看公钥cat ~/.ssh/id_ed25519.pub把输出的内容复制到 GitHub 的 Settings - SSH and GPG keys - New SSH key 里。测试连接ssh -T gitgithub.com看到Hi xxx! Youve successfully authenticated就说明配好了。提示Claude Code 本身不需要 SSH 密钥就能工作但如果你让它帮你操作远程仓库配好 SSH 会顺畅很多。5. Claude Code 安装与初始化5.1 安装 Claude Code前置条件都齐了之后安装 Claude Code 就是一条命令npm install -g anthropic-ai/claude-code-g是全局安装这样在任何目录下都能直接用claude命令。安装过程会下载包并把它放到 npm 的全局目录里通常几十秒到几分钟取决于网络速度。装完之后验证claude --version如果输出版本号说明安装成功。如果报command not found可能是 npm 全局目录不在 PATH 里。用这个命令看一下npm config get prefix输出的路径通常是/usr/local或者~/.npm-global。确保这个路径下的bin目录在 PATH 里。如果是 nvm 装的 Node.js全局包会在~/.nvm/versions/node/v20.x.x/bin下nvm 会自动处理 PATH一般不会有问题。5.2 首次启动与认证第一次运行claude会引导你完成认证。在终端里输入claude它会提示你选择认证方式。如果你有 Claude 的订阅账号选对应的登录方式它会打开浏览器让你授权。如果你用的是 API key选 API key 方式然后把 key 粘贴进去。认证信息会保存在本地配置目录里通常在~/.claude或者~/.config/claude下。认证一次之后后续启动就不需要重复登录了。我踩过的坑在某些无图形界面的服务器上浏览器授权流程走不通。这时候用 API key 方式最省事。另外如果你在虚拟机里跑 Ubuntu浏览器可能打不开授权页面可以把授权链接复制到宿主机浏览器里打开。5.3 在项目目录里初始化Claude Code 是跟项目目录绑定的。进入你的项目文件夹cd ~/projects/my-app claude启动后Claude Code 会读取当前目录的文件结构建立上下文。你可以直接问它问题比如这个项目的入口文件在哪、帮我看看 package.json 里的依赖有没有安全问题它会自己去读文件、分析、给答案。第一次在某个项目里用建议先跑一个简单命令测试 列出这个项目的目录结构并解释每个文件夹的作用看它能不能正确读取文件。如果它说找不到文件或者权限不足检查一下当前目录的权限以及你有没有在正确的目录下启动。6. 常见问题与排查技巧实录6.1 安装阶段常见报错报错一npm ERR! code EACCES这是权限问题通常是因为之前用sudo npm install装过东西导致 npm 缓存目录的属主变成了 root。解决方法sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules然后重新装。根本的解决办法是不要用sudo跑 npm如果非要全局装又没权限就配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc报错二node: command not found但明明装了这种情况通常是 PATH 没配好或者装了多个 Node.js 版本冲突。先确认which node如果输出为空检查~/.bashrc里有没有 nvm 的加载代码或者 NodeSource 装的 node 在/usr/bin/node但 PATH 被覆盖了。用echo $PATH看一下路径顺序。报错三Error: Cannot find module node:util这个报错说明 Node.js 版本太低。node:前缀的模块导入是 Node.js 16 之后才支持的Claude Code 需要 18。用node -v确认版本如果低于 18按第 3 节的方法升级。6.2 运行阶段常见问题问题一Claude Code 启动后卡住不动先检查网络。Claude Code 需要访问 Anthropic 的 API如果网络不通它会一直等。用curl -I https://api.anthropic.com测试连通性。如果公司网络有代理需要配置环境变量export HTTPS_PROXYhttp://your-proxy:port export HTTP_PROXYhttp://your-proxy:port问题二读取文件时报权限错误Claude Code 以当前用户身份运行只能读当前用户有权限的文件。如果你在/var/www或者/opt下操作可能需要调整目录权限或者用sudo启动但不推荐会有其他问题。最好的做法是把项目放在用户主目录下比如~/projects。问题三git 操作失败Claude Code 执行 git 命令时如果仓库状态异常比如有未解决的冲突、detached HEAD会报错。先用git status看一下仓库状态把问题解决了再用 Claude Code 操作。6.3 常见问题速查表问题现象可能原因解决方法npm install卡住网络慢或 registry 不可达换国内镜像源npm config set registry https://registry.npmmirror.comclaude: command not foundnpm 全局 bin 不在 PATH检查npm config get prefix把对应 bin 目录加入 PATH认证失败账号无权限或 key 无效确认订阅状态重新生成 API key读取文件报错权限不足或目录不对确认当前用户对项目目录有读写权限响应超时网络不通检查网络连通性必要时配置代理Node.js 版本报错版本低于 18用 nvm 或 NodeSource 升级到 207. 实际使用中的经验与技巧7.1 让 Claude Code 更懂你的项目Claude Code 启动时会读取项目里的CLAUDE.md文件如果存在这个文件相当于给它的项目说明书。你可以在里面写项目的技术栈、代码规范、目录结构说明、常用命令等。比如# 项目说明 这是一个基于 Next.js 的电商网站。 ## 技术栈 - 前端React 18 TypeScript - 后端Node.js Express - 数据库PostgreSQL ## 常用命令 - 开发npm run dev - 构建npm run build - 测试npm test ## 代码规范 - 使用 2 空格缩进 - 组件文件名用 PascalCase - 工具函数用 camelCase有了这个文件Claude Code 就不用每次重新理解项目回答会更准确。7.2 几个提效的使用习惯习惯一用具体指令代替模糊提问。不要说帮我优化代码而要说这个函数在处理空数组时会报错帮我加上边界检查。指令越具体输出越可用。习惯二让它先解释再动手。对于复杂改动先让它说明打算怎么改你确认没问题再让它执行。这样可以避免它改了一堆文件你才发现方向不对。习惯三善用 git 做安全网。在让 Claude Code 做大改动之前先git commit一下当前状态。这样如果改坏了git checkout .就能回滚。习惯四分步骤处理大任务。不要一次性让它重构整个项目拆成小任务一步步来每步验证结果。7.3 资源占用与性能观察Claude Code 本身占用资源很少它主要是个客户端计算在云端。但在大型项目里它读取文件、建立索引的时候会有一定的 CPU 和内存消耗。我实测在一个 5 万文件的项目里启动时大概占用 200MB 内存CPU 短暂飙到 30% 左右几秒后就降下来了。如果你觉得卡可以检查一下是不是项目目录太大或者node_modules被扫描了。可以在项目根目录放一个.claudeignore文件把不需要扫描的目录排除掉node_modules/ dist/ build/ .git/ *.log这个文件的作用类似.gitignore告诉 Claude Code 哪些目录不用看。加上之后启动速度和响应速度都会明显提升。7.4 后续可以怎么扩展Claude Code 支持 MCPModel Context Protocol协议可以接入外部工具和数据源。比如你可以让它连接你的数据库、Jira、Slack实现更复杂的自动化工作流。这部分配置稍微复杂一些需要单独写 MCP server但如果你有重复性的开发任务值得研究。另外Claude Code 可以配合 CI/CD 使用。比如在 GitHub Actions 里跑 Claude Code 做代码审查自动检查 PR 里的问题。这个场景适合团队协作能减少人工 review 的负担。我个人在实际操作中的体会是Claude Code 最大的价值不是帮你写代码而是帮你理解代码。接手一个陌生项目的时候用它来快速摸清结构、定位问题比你自己一个个文件翻要快得多。但前提是你得把环境配好Node.js 版本对、Git 配好、网络通这些基础工作做扎实了后面的体验才会顺畅。