我自己最近在 Ubuntu 上把 Claude Code 完整部署了一遍分别跑了云端服务器和本地虚拟机两个环境。Claude Code 是 Anthropic 推出的终端原生 AI 编程助手说白了就是你在终端里敲命令它能读懂你整个项目的代码结构帮你改文件、跑命令、查日志甚至梳理部署流程。这套东西对经常要 SSH 上服务器、或者习惯在终端里干活的人来说真的是能把重复劳动压缩一大截的工具。我这篇就把从零到能跑通的完整路径写清楚包括 Node 环境准备、npm 安装、登录认证、云端和本地两种场景的差异化配置以及我实际踩过的坑。目标就一个你照着做完Claude Code 不是装上了而是真的能在你的开发环境里用起来。1. 项目概述与方案选型1.1 Claude Code 到底是什么和 IDE 插件有什么区别很多第一次接触的人会把它和 GitHub Copilot、Cline 这类工具混淆。Claude Code 的核心特征是它运行在终端里不是 IDE 侧边栏窗口也不是聊天网页。你进入一个项目目录启动 claude它会去读取项目里的文件、理解目录结构、分析 git 状态然后等待你的自然语言指令。你可以说“帮我看看这个模块的依赖关系”它会自己翻代码、整理输出你也可以说“把这段逻辑改成异步调用”它会直接编辑文件改动处会呈现给你确认。这种终端原生的做法有几个实打实的好处。首先它能处理“命令执行”这种 IDE 插件很难优雅解决的问题比如编译测试、跑脚本、看服务日志、重启进程Claude Code 可以直接执行并捕捉输出。其次它对远程服务器友好只要 SSH 能连上它就能工作不需要在服务器上装图形界面。再次它的上下文就是整个项目目录不依赖某一个文件被打开这点在处理大型代码库时差异会很明显。对比维度Claude Code传统 IDE 插件运行位置终端本地或远程IDE 内嵌面板上下文范围整个项目目录git信息通常限于打开的文件或选中代码命令执行能力原生支持可读输出较弱需依赖 IDE 能力适用场景SSH 远程、终端重度用户日常编辑器内操作离线项目处理有文件读写能力视插件实现而定1.2 为什么部署环境首选 Ubuntu这个选择不是我拍脑袋定的。云端开发机、CI 构建机、容器镜像绝大多数跑的都是 Ubuntu LTS 版本尤其是 20.04 和 22.04。如果你维护的服务器是别的发行版比如 CentOS 或者 Debian那安装依赖的方式会有细微差别但 Ubuntu 的生态资料最全遇到问题搜索时基本都会有答案。另外Ubuntu 对 Node.js 这类运行时环境的支持非常直接apt 源里就有第三方工具链的兼容性也最好。本地开发环境我同样建议优先考虑 Ubuntu。一方面它跟生产环境一致避免“本地能跑、服务器跑不了”的尴尬另一方面很多常见部署任务比如搭 Doris、Zabbix、Jenkins 或者 Dify 这类服务官方文档默认给的都是 Ubuntu 命令。我后来养成了习惯凡是需要反复执行的部署流程都会丢给 Claude Code 处理省下的不只是敲命令的时间还有查文档的时间。1.3 安装前的核心思路一条链路上有三个关键点整体安装链路不复杂先是 Node.js 运行时环境然后通过 npm 全局安装 Claude Code 的 CLI 包最后做登录认证。这条链路里最容易出问题的不是安装本身而是环境准备和权限处理。第一个点Node.js 版本必须够新。Claude Code 官方要求 Node.js 18 以上我建议直接用 20 LTS 或 22 LTS因为旧版本会触发 OpenSSL 相关的兼容性报错。第二个点npm 全局安装目录的写权限。如果你是用系统自带的 Node.js全局安装时经常遇到 EACCES 权限错误这个我后面会给出两种解决办法。第三个点登录认证环节。Claude Code 支持两种认证方式一种是用 Claude.ai 的订阅账号授权另一种是配置 Anthropic API Key云端无浏览器环境下需要不同的处理方式。在动手之前你可以先确认一下自己手上的环境条件一台能跑 Ubuntu 的机器物理机、虚拟机、云服务器都行、一个能访问外网的终端、一个 Anthropic 账号或 API Key。这些准备好之后后面就只是执行命令的问题。2. 环境准备与前置依赖2.1 准备一台 Ubuntu 环境云端服务器和本地虚拟机怎么选先聊云端场景。如果你有一台云服务器系统选 Ubuntu 22.04 LTS 或者 24.04 LTS 就行配置上 2 核 4G 内存足够跑 Claude Code如果还要同时编译项目建议 4 核 8G。云服务器的好处是 24 小时在线Claude Code 可以作为团队共享的开发助手通过 tmux 挂在后台谁需要谁连上去用。本地场景的选择更多样。桌面版 Ubuntu 是最直接的安装好系统后打开终端就能开干。如果不想物理装系统用 VMware 或 VirtualBox 跑虚拟机也完全没问题快照功能还能让你在折腾环境时随时回滚这点实际用起来非常香。另外 Windows 用户也可以用 WSL2但那样的话终端环境和 Ubuntu 桌面版有一些细微差异比如 systemd 的默认行为、挂载路径的写法保险起见我建议你直接用完整版 Ubuntu。不管你选哪种方式装好系统后先做两件事。第一更新软件源和系统包sudo apt update sudo apt upgrade -y第二确认系统版本和基础工具cat /etc/os-release uname -a这一步不是走过场。后面所有命令是否兼容、遇到报错怎么查都依赖你清楚自己跑在什么内核、什么发行版上。2.2 Node.js 环境安装nvm 还是 apt我的建议很明确Ubuntu 的 apt 源里确实有 nodejs 和 npm但版本往往偏旧。比如 Ubuntu 22.04 自带的 Node.js 是 12.22早就过了官方维护期直接装来跑 Claude Code 几乎肯定会遇到问题。我的建议是使用 nvmNode Version Manager来安装和管理 Node.js原因有三个不需要 sudo 权限、可以随时切换版本、全局包不会因为系统升级而丢失。nvm 的安装方式一条命令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 use 20 node -v npm -v把 nvm 的初始化脚本写进 .bashrc 是很有必要的否则每次新开终端都要手动执行 exportecho export NVM_DIR$HOME/.nvm ~/.bashrc echo [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh ~/.bashrc source ~/.bashrc如果你实在不想用 nvm也可以直接从 NodeSource 仓库装curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这条路径也能拿到较新的 Node.js 20适合不喜欢多一层版本管理工具的人。2.3 Anthropic 账号与密钥准备两种认证方式适用场景不同Claude Code 部署完之后必须要通过认证才能调用模型。认证方式有两种我建议你在动手安装前就把账号准备好免得装完了卡在最后一步。第一种Claude.ai 订阅账号。如果你有 Claude.ai 的 Pro 或 Max 订阅在终端里执行 claude 命令后它会生成一个一次性登录链接你用浏览器打开、授权、再把授权码贴回终端就可以完成登录。这种方式对本地桌面环境非常方便因为你本来就有浏览器。第二种Anthropic API Key。在 Anthropic Console 的 API Keys 页面创建密钥然后通过环境变量 ANTHROPIC_API_KEY 来指定。这种方式更适合云端服务器场景因为没有图形界面的服务器没法完成浏览器授权。你可以把密钥写进 ~/.bashrc 或 ~/.zshrcexport ANTHROPIC_API_KEY你的密钥这里有个重要的安全纪律不要把 API Key 直接写进项目目录里的任何文件尤其是会被 git 跟踪的文件否则一提交到仓库就等于把密钥公开了。我更推荐使用 --env 参数或者在 shell 配置里单独维护后面讲权限安全时还会细说。3. 安装部署实操一步步跑通3.1 npm 全局安装 Claude Code 与版本验证环境准备好之后安装过程其实就一条命令npm install -g anthropic-ai/claude-code如果你没有配置过 npm 的 registry这一条命令可能会因为网络原因比较慢。在国内网络环境下我建议先把 npm 的 registry 切换到国内镜像源这样下载速度会明显提升也更省心npm config set registry https://registry.npmmirror.com设置完再重新执行安装命令就好。安装完成后先验证 CLI 是否可用claude --version能看到类似 1.0.x 之类的版本号输出就说明安装成功了。如果没有这个命令大概率是 npm 的全局 bin 目录没有写进 PATH排查方法我放在后面的常见问题章节。这里额外说一句Claude Code 的更新频率其实挺高的官方推荐直接用 npm 的全局更新命令npm update -g anthropic-ai/claude-code我一般会隔一两周更新一次确保用到最新的模型能力和 bug 修复。3.2 登录认证从浏览器授权到无浏览器环境的处理首次执行 claude 命令时它会自动引导你完成登录。本地桌面环境下终端里会显示一个形如 https://claude.ai/login?authxxx 的链接和一段一次性授权码。你需要在默认浏览器里打开那个链接登录你的 Claude 账号然后输入终端显示的授权码确认后回到终端就能看到登录成功的提示。云端服务器场景就得换思路了。因为服务器上没有浏览器claude 命令会请求你使用 --login 模式并提供一个手动授权链接。实际做法是在本地电脑的浏览器里打开链接、登录并授权然后把授权码带回服务器终端粘贴完成。注意这个过程里服务器终端会一直保持等待状态不要关掉。用 API Key 的方式会更直接不需要走浏览器授权。设置好环境变量 ANTHROPIC_API_KEY 后启动 claude工具会直接尝试使用这个密钥。验证是否生效可以输入一个最简单的指令比如“你好确认你能正常工作”它能正常回复就说明认证环节已经跑通。3.3 云端服务器部署SSH 连接与 tmux 长会话保持云端部署和本地部署最大的区别在于会话保持。如果你直接用 SSH 连接服务器、前端启动 claude那么网络一抖、连接一断Claude Code 就跑没了正在进行的任务也全部中断。这不是工具本身的问题是 SSH 会话的天然限制。我推荐用 tmux 来解决。tmux 是一款终端复用工具能让会话在 SSH 断开后继续在后台运行下次连上来还能重新附着。安装很简单sudo apt install -y tmux创建一个新的会话tmux new -s claude在这个会话里启动 claude之后哪怕 SSH 断开claude 也会一直在运行。下次重新 SSH 连上服务器后用下面的命令恢复到之前的会话tmux attach -t claude第一次用 tmux 可能会觉得快捷键反直觉但你只需要记住几个就够Ctrlb 然后按 d 是分离会话Ctrlb 然后按 s 可以切换会话列表。这个组合拳我实测用来跑耗时的部署任务是真好用Claude Code 在一边跑你可以随时断网走人回来看结果就行。3.4 本地 Ubuntu 桌面环境的额外配置终端、PATH 与编辑器联动本地桌面环境下装好 claude 之后通常还会顺手做一些配置让日常使用更顺手。首先是 PATH 问题。如果你用 nvm 安装 Node.jsnpm 全局包的 bin 目录默认是 ~/.nvm/versions/node/v20.x.x/bin正常情况下 nvm 会自动把它加进 PATH。但如果 claude 命令找不到可以手动确认which claude没有输出的话就把下面这行加进 ~/.bashrcexport PATH$HOME/.nvm/versions/node/$(ls ~/.nvm/versions/node | tail -1)/bin:$PATH其次是终端的选择。GNOME Terminal 其实已经够用但如果你打算长时间跟 Claude Code 交互我建议试一下 Tilix 或 Terminator它们支持分屏可以把 Claude Code 放在一侧另一侧跑你自己的命令对照起来非常方便。最后是编辑器联动。Claude Code 编辑文件之后你的编辑器需要能立刻感知到文件变化。VS Code 有个很好的特性Claude Code 修改完文件如果你在 VS Code 里打开了对应的项目目录它会自动检测到外部文件变化并重新加载。配合我后面要讲的项目级配置整个体验会非常顺滑。4. 核心配置与典型工作流4.1 首次启动、常用斜杠命令与交互方式启动 Claude Code 的正确姿势不是直接在空目录里敲 claude而是先进入一个真实项目目录cd /path/to/your/project claude启动后你会看到一个交互式的终端界面输入自然语言指令即可。比如“分析这个项目的模块结构并输出 Markdown 文档”它会读取项目文件、分析、然后输出一份结构化的结果。如果让它改代码它会把改动以 diff 形式展示出来并询问你是否接受。掌握几个斜杠命令会让工作效率提升很多命令作用/help查看帮助文档/init在项目中初始化 CLAUDE.md 配置文件/clear清空当前对话上下文/compact压缩对话历史保留关键信息/status查看当前会话状态和上下文占用其中 /clear 是我用得最多的。上下文窗口是有限的当对话越来越长、模型开始“忘事”或者响应变慢时执行 /clear 能立刻清爽。需要说明的是 /clear 不会删除对话记录只是重置当前会话的上下文窗口。4.2 项目级规范文件 CLAUDE.md让 Claude Code 更懂你的项目CLAUDE.md 是 Claude Code 的一个核心配置作用相当于给 AI 一份项目说明书。放在项目根目录之后每次启动 claude 它会自动读取这个文件并将里面的内容作为项目的背景信息。比如一个项目根目录的 CLAUDE.md 长这样# 项目说明 这是一个基于 Python FastAPI 的订单服务使用 PostgreSQL 存储数据。 # 代码风格 - 使用 SQLAlchemy 2.x 异步写法 - 所有接口返回 JSON统一结构为 {code: 0, data: {...}} - 路由文件放在 app/api/v1/ 目录下 # 常用命令 - 启动服务uvicorn app.main:app --reload - 跑单测pytest tests/ # 约束 - 不要修改 migrations 目录下的已有迁移文件 - 涉及数据库改动时先补迁移脚本有这个文件之后Claude Code 提建议的准确性会上一个台阶。比如你让它写一个新接口它会主动按照项目既有的返回结构来而不是自由发挥另一套风格。首次部署完我强烈建议先让 claude 帮你生成一份 CLAUDE.md 初稿执行 /init 它会自动扫描项目并生成一份你再手动改改就行。这个方法培养起来之后新项目的上手效率会提升非常多。4.3 与 VS Code 和现有工具链的协作如果你日常开发用 VS CodeClaude Code 可以跟你已有的工作流无缝衔接。方案有两种第一种直接在 VS Code 内置终端里运行 claude。VS Code 的终端本质上就是一个常规 Linux 终端claude 启动后在终端里输出VS Code 完全可以正常显示。这种方式的优点是零额外配置缺点是没有图形化的 diff 展示。第二种安装 Claude Code 官方 VS Code 扩展。在扩展商店里搜索 Claude Code 安装后它能更紧密地集成代码变更会在侧边栏里展示、多文件变更可以看到列表、甚至可以在 IDE 里直接发起对话。我自己是把两种方式搭配用简单的脚本修改用 VS Code 扩展复杂的多文件重构或需要跑命令时切到独立终端里操作。另外如果你习惯在终端里定义 alias可以加一条alias ccclaude --dangerously-skip-permissions这个 alias 本质上是跳过权限确认我一般只在非常信任的脚本环境里用日常建议还是用默认的逐次确认模式原因下面会讲。4.4 权限响应机制与安全边界Claude Code 要执行命令或修改文件时会弹出权限请求。这是它跟纯聊天工具最大的不同也是我判断这个工具“可用”的一个关键标准不是所有终端 AI 助手都能做到有边界感。权限确认分为几类执行 bash 命令时、写文件时、同时修改多个文件时都会单独征求许可。第一次使用的人可能会觉得频繁确认很烦但这是必要的安全护栏。尤其当 claude 试图执行 rm 这类危险命令时它会明确展示完整命令并要求确认我不会为了图快而盲目跳过所有确认。这里必须提醒一句--dangerously-skip-permissions 这个参数能跳过所有权限确认看起来“效率高”但风险非常大。如果你让模型在错误的目录下执行了清空类的操作没有确认机制兜底后果只能自己承担。我个人的建议是仅在隔离环境、测试环境、或者非常信任的目标目录下使用生产环境请务必保留逐次确认。API Key 的保护也应该纳入安全习惯。在 shell 里设置 ANTHROPIC_API_KEY 时注意不要在终端历史里暴露完整密钥更不要写进会被 git 提交的文件。可以用 export 临时设置或者把密钥放到单独的配置文件里引用。5. 常见问题与排查实录5.1 安装阶段EACCES 权限错误与 Node 版本过低安装时最典型的报错是 npm 的 EACCES 权限错误。如果你是用 apt 装的 Node.jsnpm 的全局目录可能是在 /usr/lib/node_modules 或 /usr/local/lib/node_modules普通用户没有写权限安装时就会弹出一大段 error。解决方案有两个一是给 npm 目录加上当前用户的写权限二是切换用户重新执行。我推荐直接改用 nvm因为装在自己的用户目录下天然就没有这个问题。另一个高频问题是 node 版本过低npm install 的阶段可能不报错但运行 claude 直接抛 ERR_OSSL_EVP_UNSUPPORTED。这就是 Node 版本兼容性问题比如 Node 12 跑一些新加密库就会遇到。解决方式很直接升级到 Node 18 以上最好直接上 20 LTS。你可以用 nvm install 20 快速切换验证版本号后再重装 Claude Code。npm 下载慢或安装超时也比较常见。检查一下当前 registry 配置npm config get registry如果是默认的 https://registry.npmjs.org切换成 https://registry.npmmirror.com 基本能解决下载缓慢的问题。切换之后再执行安装命令体感会有明显差别。5.2 登录与认证阶段授权码失效、无浏览器、反复要求登录本地环境下登录经常遇到的一个情况是浏览器已经完成授权但终端一直停在“等待授权”状态。通常是授权码已过期或者浏览器打开的登录链接不是最新的。解决办法是退出登录状态后重新走一遍流程重点确认授权码是终端里最新显示的那一串而不是页面缓存里的旧码。云端无浏览器环境的登录问题我自己遇到过一种情况终端生成的链接在本地浏览器能打开但授权后返回终端却提示失败。排查下来是因为用的账号跟 API Key 不是同一个组织下的。简单说就是如果你在终端里已经设置了 ANTHROPIC_API_KEY又试图用 Claude.ai 订阅账号授权两者会产生冲突。建议明确选一种认证方式不要混用。还有一种情况是 claude 命令每次启动都要求重新登录。这通常是因为配置目录的权限问题或者 HOME 环境变量指向了意外的路径。检查一下当前用户对 ~/.claude 目录是否有写权限权限不对就重新授权一次。5.3 使用阶段文件写入失败、权限拒绝与日志排查Claude Code 在项目里写文件失败通常是项目目录对当前用户没有写权限。比如在 /opt 或 /var/www 这种由 root 持有的目录下启动 claude它会提示没有权限写入。解决思路是给当前用户相应的目录权限或者在普通用户自己的家目录下创建工作目录不建议直接切 root 跑开发工具。遇到请求报错、模型返回异常等运行时问题可以查看本地日志默认在 ~/.claude 目录下。以管理员模式启动也行但更简单的是直接用对话上下文排查。很多情况下“工具没反应”并不是报错而是权限请求被忽略了仔细看终端输出找到最新的权限提示并及时响应就好。5.4 问题排查速查表我把上面遇到的典型问题按场景整理成一个速查表方便你实际排查时定位问题现象可能原因处理方式npm install 报 EACCESnpm 全局目录无写权限换 nvm 安装或修改目录权限claude 启动报 ERR_OSSLNode 版本过低升级到 Node 18推荐 20 LTSnpm 安装速度慢默认 registry 访问慢切换到 npmmirror 源登录过程卡住授权码过期或账号冲突确认最新授权码避免 API Key 与订阅账号混用每次启动都要登录~/.claude 目录权限异常修复目录权限或重新授权写文件提示无权限项目目录对当前用户不可写调整目录归属或用普通用户目录claude 无响应权限请求被忽略检查终端最新输出中的允许/拒绝请求对话太长老是忘上下文上下文窗口已满执行 /clear 或 /compact 清空压缩上下文5.5 几条亲测有效的使用习惯最后分享几个我实践中整理出来的使用习惯不见得写在官方文档里但对日常效率影响很大。第一每次新建一个真正要干活的项目第一件事就是让 Claude Code 生成 CLAUDE.md。它会把项目的目录结构、构建命令、代码风格这些信息固化成文件之后所有对话质量都会明显提升。第二涉及多文件修改的重构任务我会先明确告诉它“先分析影响范围再列出修改计划最后动手改”这个约束能避免它一上来就大改特改。第三不要在一个会话里塞太多不相关的任务相关的任务放在一个会话里能利用上下文优势不相关的任务开新会话更好上下文越干净输出越准。还有一个小技巧如果你给 claude 的指令比较复杂可以先让它复述你的需求确认理解一致后再执行。这个步骤看着多花一点时间实际能省掉很多因为误解导致的大改。我自己实测下来复杂任务先对齐再执行成功率至少提高一半。6. 从“能跑起来”到“真正好用”的几点体会部署这件事跑通只是起点。Claude Code 真正好用起来需要你在工作流里找到一个合适的定位。我自己现在的习惯是它负责“执行”和“检查”我负责“方向”和“决策”。遇到不熟悉的报错它帮我查上下文、验证思路遇到重复的部署任务它按我确认过的命令逐步完成遇到大规模的代码重构它给我方案、我把握边界。它不是一个替你做决定的工具而是一个把你的手速放大很多倍的执行器。配置上最值得花时间的还是 CLAUDE.md。把它当作项目的“交接文档”来维护每次项目结构变化、命令变化都同步更新越是这样 Claude Code 越像是一个长期跟项目长大的助手而不是每次重新认识代码库的新人。现在我做新环境部署时也已经习惯了先装 nvm、再装 Node 20、然后 npm 装 Claude Code 这条固定路线整个流程跑下来比最初摸索时节省了大半时间。