上个月我把一台放了很久的 Ubuntu 机器重新擦干净装成开发机折腾完 Claude Code 之后整个终端工作流基本就离不开了。说实话这类 AI 编程工具在网页上用和在终端里用完全是两种体验——Claude Code 直接跑在命令行里能看懂整个项目仓库改起代码来像有个同事坐在旁边给你递补丁。这篇教程就是我从零开始在一台干净的 Ubuntu 系统上完整部署 Claude Code 的记录包括本地桌面环境和云端服务器两种跑法。如果你正准备把 Claude Code 装到自己的 Linux 开发环境里跟着一步步走就行。1. Claude Code 到底是什么为什么值得装进 Ubuntu 终端先聊清楚一个事情Claude Code 不是一个网页套壳也不像有些工具那样只给你生成一段代码让你自己复制粘贴。它本质上是一个跑在终端里的 AI 编程助手启动之后你可以用自然语言直接跟它对话比如帮我把这个模块的重试逻辑整理一下、给这个函数补单元测试、查一下为什么这个接口偶发超时。它会自己去读项目文件、搜索代码、执行测试命令然后用 diff 的形式把改动直接呈现在你面前你确认之后才会写入文件。1.1 和网页版、IDE 插件的核心区别网页版适合单次问答但它看不到你的完整项目结构和历史改动IDE 插件需要你打开编辑器才能用云端服务器或者纯命令行环境下很难集成Claude Code 运行在终端里跟 Git、SSH、项目目录天然贴合特别适合远程开发、CI 脚本、服务器运维这类场景我在实际使用中最明显的感受是它不挑环境。只要有一台能跑 Node.js 的 Linux 机器你就能用。对于经常要 SSH 到云服务器上排查问题的场景这个东西比开一个完整的 IDE 轻太多。1.2 适合谁来用用 Ubuntu 做主力开发机的后端工程师、运维工程师在云服务器上跑自动化任务、需要 AI 辅助写脚本和排查日志的人想把手头的 AI 工具链从网页问答升级到项目级操作的开发者1.3 它到底能帮你做什么举个我自己的实际案例之前有个旧项目里有大量重复的 HTTP 请求封装每个文件里都复制粘贴了一大段。我用 Claude Code 在项目根目录启动输入一句把公共请求逻辑提取成一个工具函数所有文件改成调用它它直接列出了涉及的文件清单、改动方案和风险点我确认后就逐个文件改完了。如果让我自己手动改至少一小时起步那次整个过程不到十分钟。2. 动手安装之前先检查这三件事很多人在 Ubuntu 上装 Claude Code 卡住其实卡住的点都特别基础Node.js 版本太老、npm 版本不对、或者压根没确认过自己的登录凭证。所以我在这一步会多说几句别急着敲安装命令。2.1 Node.js 版本老 Ubuntu 最常见的坑Claude Code 是 Node.js 写的对运行环境有最低版本要求。按照官方说明Node.js 18 以上的版本可以正常运行但我的实际建议是直接上 Node.js 20 LTS 或者更高。如果你是新装的 Ubuntu 20.04 或者 22.04直接apt install nodejs装出来的版本往往只有 10.x 或者 12.x这个是跑不起来的。我整理了一张版本情况对照表Ubuntu 版本apt 默认 Node.js能否直接跑 Claude Code建议方案20.04 FocalNode.js 10.x不能用 nvm 安装 Node.js 20 LTS22.04 JammyNode.js 12.x不能用 nvm 安装 Node.js 20 LTS24.04 NobleNode.js 18.x勉强可以但建议升级用 nvm 安装 Node.js 20 LTS提示不是你手动编译一个高版本 Node.js 就能解决所有问题关键是npm和npx命令也要跟着新版本走。如果你已经在系统里装过低版本 Node.js之后再装 nvm 可能会遇到命令冲突建议先看清楚现在的执行路径。2.2 npm 的配置和权限EACCES 错误都是从这里来的Ubuntu 的系统级npm在全局安装包时经常遇到权限问题最典型的就是执行npm install -g的时候报EACCES: permission denied。遇到这个情况我不推荐直接用sudo npm install那样会把所有全局包都装到 root 目录下后续用起来容易出乱子。更稳妥的办法就是直接装一个nvm让 Node.js 和你安装的全局包都放在当前用户目录下彻底绕开/usr/lib/node_modules的系统写权限问题。这部分我会在下一章详细写步骤。2.3 登录凭证准备Claude Code 在使用前需要完成一次身份认证。你需要有一个可用的 Claude 账号然后按照终端里的提示完成授权。如果你是在本地桌面版的 Ubuntu 上操作会弹出浏览器窗口确认权限如果是在纯命令行的云端服务器上操作流程会稍微不一样后面第四节会单独说。这里强调一句如果你已经可以正常登录 Claude 官网使用服务认证这一步基本就是顺畅的准备好对应账号的邮箱和密码就行。3. 一步一步装好 Claude Code我用的完整命令记录这一章纯步骤你照着敲就行。我尽量把每一步为什么这么做讲清楚遇到问题也知道怎么回头查。3.1 第一步用 nvm 安装 Node.js 20 LTS我个人非常推荐用 nvm 来管理 Node.js 版本尤其你以后可能还要跑其他 Node 项目。nvm 最大的好处是不同项目的 Node 版本可以切换不会互相污染。先安装 nvm 的依赖基础然后拉取安装脚本sudo apt update sudo apt install curl git curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成之后重新打开终端或者执行下面的命令让 nvm 生效export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后装上 Node.js 20 LTSnvm install 20 nvm alias default 20 node -v npm -v看到v20.x.x和对应的 npm 版本这一步就算过了。我在这台机器上跑的是 v20.18.0Claude Code 的安装过程没有遇到任何版本兼容问题。注意如果你打开新的终端后node命令找不到多半是 nvm 环境变量没有自动写入~/.bashrc检查一下安装脚本是否在.bashrc末尾追加了相关配置没有的话手动加进去。3.2 第二步安装 Claude CodeNode.js 环境就绪后安装 Claude Code 就一条命令的事npm install -g anthropic-ai/claude-code这一步会从 npm 仓库拉取包然后做全局安装。装完之后验证一下claude --version如果终端能输出类似1.x.x的版本号说明核心程序已经装好了。这时候你就已经可以在任意项目目录里启动claude了。我在实际安装中看到这个包有一些原生模块依赖npm 在安装时会自动处理正常情况下不需要你手动装其他编译工具。但如果你用的是比较精简的 Ubuntu Server 版本缺了build-essential的话理论上也可能触发 node-gyp 编译问题保险起见可以提前执行sudo apt install build-essential3.3 第三步首次启动和认证在准备用 Claude Code 的目录里直接输入claude第一次运行时它会提示你完成登录。桌面版 Ubuntu 会打开浏览器跳转到授权页面你确认账号并授权就行。如果你是纯命令行环境它会给你一个一次性验证码或者跳转到专门的授权链接完整的流程会出现在终端里按提示操作即可。认证完成后程序会把凭证信息保存在当前用户目录的配置文件中之后使用就不需要反复登录了。提示这个凭证文件建议做好备份尤其是云端服务器场景重装系统后直接复用能省掉重新认证的麻烦。3.4 第四步在项目目录里跑通一次完整对话认证完毕随便进入一个你的代码项目输入claude它会扫描项目文件并给出一些项目理解的提示。此时你可以试着问一句帮我看看这个项目的目录结构然后告诉我哪些地方最值得增加测试。如果它正常回复并且你能看到它对文件进行了检索和引用恭喜你这次安装就算真正跑通了。4. 本地桌面版和云端服务器两种部署跑法有什么不一样很多人忽略一个问题在同一套安装步骤下本地 Ubuntu 桌面机和云端 Ubuntu 服务器在认证方式、进程管理、权限控制上其实是有区别的。这一章我把两种环境的差异和各自的部署建议拆开讲。4.1 本地桌面 Ubuntu适合日常编码和交互式使用本地环境最省心。认证走浏览器使用走交互式界面你直接在一个终端窗口里启动claude就像打开一个集成在项目里的聊天窗。本地跑法的核心优势是可以随时用图形界面查看改动后的文件、跑 git diff需要看代码运行结果时可以并行开多个终端不受 SSH 断连影响进程挂在本地我现在的主力开发机就是 Ubuntu 桌面系统平时写代码、改配置、查日志全在终端里完成。Claude Code 和 VSCode 的终端也可以配合使用你在编辑器里写好代码后直接在底部终端启动claude它会自动识别当前工作目录。4.2 云端无桌面服务器适合自动化、批处理和长时间任务云端服务器通常没有图形界面你通过 SSH 连接所有操作都是纯文本。这种场景下 Claude Code 同样可用但我建议注意三个点。第一认证流程。无头服务器上没有浏览器你需要用终端里给出的授权链接在本地电脑浏览器打开并完成认证然后把会话令牌复制回服务器。这个流程官方支持按照提示操作就行。第二保持会话。用 SSH 连接云服务器时如果连接中断正在运行的claude进程就会收到挂断信号。我一般用tmux或者screen把会话挂起来这样即使 SSH 断了Claude Code 还能继续执行之前的任务。命令大致是这样tmux new -s claude-session claude # 需要退出时先按 Ctrlb再按 d 分离会话 # 之后使用 tmux attach -t claude-session 重新接回第三权限控制。云端服务器通常有多个开发者和自动化任务共存给 Claude Code 一个尽量小的权限范围更稳妥。我一般不让它直接访问整个文件系统而是通过项目的权限配置把可操作范围限制在当前目录下。4.3 一台机器上同时跑多个项目实例如果你的开发状态是同时维护多个项目可以每个项目开一个终端窗口分别启动claude它会把各自的目录作为工作上下文互不干扰。官方还支持通过配置项指定工作目录这个后面在进阶配置里讲。5. 安装部署过程中我踩过的坑完整排查链路每次写教程我都想把踩坑排查的过程放进来因为直接告诉你这样做就能成功其实价值有限真正能帮你节省时间的往往是怎么定位问题。5.1 坑一Ubuntu 系统自带的 Node.js 太旧导致启动报错第一次在一台 Ubuntu 22.04 机器上装我图省事直接用了默认的 apt 源安装 Node.jssudo apt install nodejs npm当时查版本node -v # v12.22.9装完 Claude Code 后执行claude --version结果报了一连串的语法错误。这种错误通常不是 Claude Code 本身的问题而是 Node.js 版本过低代码里用了高版本才支持的语法特性旧版本解析不了。排查思路先看 Node.js 版本确认是不是太低再看which claude指向的全局路径是否和当前 Node.js 属于同一套环境。我最后删掉 apt 装的旧版本改用 nvm 装上 Node.js 20问题直接消失。5.2 坑二npm 全局安装时出现 EACCES 权限报错如果你没有用 nvm 而是保留了系统级的 Node.js执行npm install -g很可能遇到这个报错npm ERR! code EACCES npm ERR! syscall mkdir npm ERR! path /usr/lib/node_modules/anthropic-ai原因很直接全局安装包需要写/usr/lib/node_modules目录而这个目录归 root 所有当前用户没有写权限。很多人会顺手加sudo我当时也试过虽然能装上但后面 npm update 和卸载都会带上权限泥潭。所以我现在遇到这种情况都会劝一句别跟权限较劲直接切换到 nvm 或者通过设置 npm 全局目录到用户目录来解决。5.3 坑三认证成功后claude仍然提示未登录这种一般不是安装问题而是凭证没有落盘成功。常见原因是你使用了sudo安装了 Claude Code或者启动时用了sudo claude导致它把凭证写到了 root 用户目录而你自己用户的终端读不到。排查思路检查~/.claude目录是否存在且有正常内容如果你刚才用 sudo 跑过也可以直接对比/root/.claude目录。遇到过好几个人问我为什么明明登录成功了下一次又要登录基本都是这个原因。5.4 坑四claude命令找不到这种情况最常出现在装是装成功了但新开的终端找不到命令上。原因通常是 nvm 相关的环境变量没有加载或者 npm 全局目录不在 PATH 里。排查链路which npm npm config get prefix ls $(npm config get prefix)/bin | grep claude如果最后一条找不到 claude说明安装路径异常如果找得到但新终端不认就去~/.bashrc里看 nvm 的初始化配置是否确实生效了。5.5 坑五云端无头服务器上认证链接打不开在云服务器上首次认证时终端会输出一个授权链接。很多人习惯直接在服务器上用文本浏览器去开那个体验很差。正确做法是把链接复制到你自己电脑的浏览器里打开完成授权后回到服务器终端继续。这个流程不复杂但如果不清楚原理很容易卡在链接打不开这一步。6. 装完之后这几种配置能让它更好用安装只是开始。经过这段时间的使用我发现下面几个配置项和习惯对实际效率提升最明显。6.1 利用项目里的 CLAUDE.md 文件固定上下文Claude Code 会读取项目根目录下的CLAUDE.md文件作为长期记忆。你可以在这个文件里写清楚项目的技术栈、代码风格、常用命令、目录结构甚至是你希望 AI 遵守的编码规范。它每次启动都会自动加载这个文件相当于给 AI 做了一次项目培训。我自己的模板长这样# 项目提示词 ## 技术栈 - 后端Python 3.11FastAPI - 前端React 18Vite ## 常用命令 - 运行测试pytest tests/ - 启动开发服务uvicorn app.main:app --reload ## 编码规范 - 类型标注必写 - 不使用全局变量 - 数据库操作统一走 SQLAlchemy session刚接触这个功能的时候我也觉得麻烦但写完之后 Claude Code 给出的建议质量和代码风格确实有明显提升。6.2 权限控制把 AI 限制在当前目录内在多用户机器上使用或者只是单纯不想让 AI 乱动系统文件可以开启权限限制模式。启动时加一个参数claude --permission-modeaplan这个模式会对文件改动和命令执行先给出方案等你确认后再动手适合在涉及敏感文件的时候使用。默认的对话式确认适合日常开发但如果你要睡觉前挂一个长任务跑建议给足够的权限并提前审查任务内容。6.3 更新到最新版本Claude Code 的迭代速度不慢官方也提供在终端里直接更新的命令claude update如果这个命令不可用也可以通过 npm 手动更新npm update -g anthropic-ai/claude-code我个人的习惯是每周更新一次既能用上新功能也能避免跨版本过大导致的配置不兼容。6.4 用环境变量注入 API Key个人开发或者自动化脚本场景里你可能不想走交互式登录认证而是直接用 API Key 方式接入。这样可以在系统环境变量里设置好密钥让 Claude Code 启动时自动读取。这个方式在 CI/CD 流水线里尤其有用不用人工干预凭证。具体环境变量名和文档建议以你部署时最新版本的信息为准装完可以先用claude --help看一下当前的认证和相关配置选项。写在最后的一些使用心得装好只是第一步真正让它变成生产力工具关键还是要养成把项目背景讲清楚、把任务拆细的习惯。我现在每次让它做重构之前都会先在对话里把约束条件说完整比如不要动公共接口签名保持向后兼容新增的代码必须带单元测试。这样给出来的改动基本不用大调。另外用它跑那些重复度高、模板化程度高的任务比如批量加注释、统一日志格式、修 lint 报错是真的省心但涉及架构决策、数据迁移这类要综合考虑业务背景的事情我还是习惯自己拿主意让它负责把方案细节落地和查漏。如果这份记录能让你在 Ubuntu 上的安装和上手过程少绕一些弯那就很值了。