直接把结论放在最前面如果让我在当下选一个最值得花时间折腾的AI编程工具我第一个推荐的就是 Claude Code。它不是那种在网页对话框里陪你聊天、最后甩给你一段代码让你自己复制的AI而是一个能真正钻进你项目目录里干活的编程智能体——读代码、改文件、跑命令、调参数、提交Git记录一条龙推进。这篇文章的目标读者很明确你人在国内电脑环境可能比较乱想从零把 Claude Code 装起来然后亲手写完一个小工具。我会把安装前的环境准备、安装过程的每个步骤、第一次启动的认证和权限配置再到一次完整的代码实战全部按实际执行顺序捋一遍顺手把我这一年里踩过的坑也一并倒出来。我知道这标题看着像营销号但内容我不打算注水。B站上关于 Claude Code 的教程已经不少了但很多只停在“装好了、能聊天了”这一步真正讲清楚怎么用它干活、怎么配合项目文件、遇到权限拦截怎么处理的内容并不多。所以这篇文章默认你是一个刚接触命令行的新手只要你照着抄命令基本都能跑起来如果你已经有基础可以直接跳到后面的实战和配置章节那两段的含金量更高。1. 安装前先搞清楚Claude Code 是什么需要什么环境1.1 它不是聊天网页而是一个会动手的智能体Claude Code 是 Anthropic 官方出品的命令行 AI 编程智能体本质上是一个跑在终端里的 CLI 工具。你启动它之后它会进入你当前所在的项目目录读文件、看目录结构然后根据你给出的自然语言任务自己规划步骤并动手实现。它不只生成代码给你它还会自动执行命令比如安装依赖、跑测试、查看报错再根据结果继续修改。这里对比一下网页端 AI 工具差别特别明显。网页端给的是“代码片段”你还要自己复制、保存、调试Claude Code 给的是“完成的结果”它会自己把文件写好、把命令执行完再告诉你现在项目处于什么状态。对一些重复性高、规则清晰的任务比如重构函数、补充单元测试、批量处理文件它都能独立完成你只需要在关键节点做检查。它的可运作能力来自四个基础设计能读写本地文件、能执行终端命令、能长期追踪项目上下文、能在失败后自我修正。这四件事组合起来就让它从“问答工具”变成了“能交付成果的初级开发”。这也是为什么 AI 大模型生态里Claude Code 能在短时间里火起来。1.2 安装前建议具备的 4 个环境安装 Claude Code 本身不需要很高配置但有几项基础环境建议先准备好。我按重要性排了个序项目最低要求推荐配置作用Node.js18.x20 LTS 及以上Claude Code 依赖 npm 安装和运行npm随 Node.js 自带9.x 以上包管理工具用于安装 CLIGitGit 2.x最新版配合版本管理和代码提交API 访问能力能访问 Anthropic 接口稳定低延迟登录认证与模型调用前三项在今天几乎任何开发电脑上都有没装的话下面章节我会给出完整步骤。第四项在国内场景里比较特殊我单独放到后面详说。这里你只要记住Claude Code 本身是免费安装的但真正跑模型需要你有一个可用的 API 入口没有它装完之后也只能停在欢迎页。1.3 API Key 可以提前准备好API Key 是 Claude Code 调用大模型的通行证。如果你打算走官方通道可以去 Anthropic 的开发者控制台注册账号创建一个 API Key格式一般是sk-ant-...开头。如果你当前网络环境访问官方接口不稳定也别着急现在有很多云服务商提供 Anthropic 模型的兼容 API 转发服务同样可以拿到 Base URL 和 Key。我的建议是在安装之前就把 Key 准备好。因为很多新手装完 Claude Code 后卡在登录那一步第一反应是以为安装出了问题来回卸载重装好几遍其实是 API 访问的问题。提前准备好网络链路和密钥后面启动会话就一气呵成。2. 保姆级安装从零把 Claude Code 装到电脑上2.1 先装 Node.js 和 npmWindows 为例Node.js 是 Claude Code 的运行底座。去 Node.js 官网下载 LTS 版本的安装包注意选 20 或 22 的 LTS不要选最新的非稳定版。安装过程一路 Next 即可这里有一个细节安装到“Tools for Native Modules”那一步时别取消勾选它会把一些必要的编译工具链一起装上以后用 npm 装带原生模块的包会省很多事。装完打开一个全新的终端窗口老窗口拿不到新的环境变量执行下面两条命令确认版本node -v npm -v正常会输出类似v20.18.0和10.x.x的数字。如果你用的 Windows建议把终端切到 PowerShell 或者 Windows Terminal不要用老掉牙的 cmd字体显示和复制粘贴体验都好很多。npm 安装源在国内经常慢得让人抓狂我建议你直接在全局层面改成 npmmirror 镜像源npm config set registry https://registry.npmmirror.com改动之后可以用npm config get registry验证看到返回 npmmirror 的地址就说明生效了。这一步能帮你后面安装 Claude Code 时少等很多时间。2.2 安装 Git 并完成基础配置Git 不是 Claude Code 运行的硬依赖但实际使用中几乎离不开它。你让 Claude Code 帮你改代码、建项目、提交版本它内部会频繁调用 Git 命令如果系统里没有 Git很多自动化操作会直接报错。安装依旧建议去 Git 官网下载 Windows 版本安装选项除默认外建议在“Adjusting your PATH environment”那步选择 “Git from the command line and also from 3rd-party software”。安装完成后设置一个基础身份信息否则后续提交代码会提示用户名和邮箱不完整git config --global user.name 你的名字 git config --global user.email 你的邮箱验证方式git --version走到这一步你的电脑已经有了一套不需要打开 IDE 就能跑代码的完整环境。2.3 用 npm 安装 Claude Code环境就绪之后安装本体只需一条命令npm install -g anthropic-ai/claude-code加-g表示全局安装这样你在任意目录下的终端都能直接使用claude命令。安装过程大概几十秒到两三分钟取决于网络状况。装完执行claude --version如果输出一个版本号比如1.0.x说明安装成功。如果提示“claude 不是内部或外部命令”大概率是 npm 的全局路径没加到系统 PATH 里这在 Windows 上比较常见。你可以先执行npm prefix -g拿到全局目录再把那个目录加到环境变量的 Path 里重新开终端就能解决。后续如果官方发布了新版本不需要重新走一遍安装流程直接在终端里执行claude update它会自动检查并升级到最新版。我个人的经验是保持版本更新很重要官方迭代很快很多修 bug 和新功能都只在最新版本里体现。老版本容易碰见授权过期、模型调用异常这种莫名其妙的问题。2.4 macOS 和 Linux 用户怎么装macOS 用户最省事的方式是用 Homebrewbrew install node git npm install -g anthropic-ai/claude-codeLinux 用户优先用系统自带的包管理装 Node.js 18比如 Ubuntu 上执行sudo apt update sudo apt install nodejs npm git npm install -g anthropic-ai/claude-code需要注意Ubuntu 自带的 Node.js 版本通常偏老拿到版本号以后先检查是否满足 18。如果版本过低建议用 NodeSource 或 nvm 安装一个新版 Node。别嫌麻烦Claude Code 对 Node 版本有硬性要求版本不够它装完也无法正常启动。3. 第一次见面认证登录与权限管理3.1 登录并关联 API Key装完以后进入你的项目目录比如cd my-project输入claude第一次运行会进入登录引导流程。官方支持两种方式一是通过浏览器登录 Claude 账号完成 OAuth 授权二是在终端里直接粘贴 API Key。如果你没有 Anthropic 官方账号或者网络链路走的是兼容 API 转发建议直接用第二种方案。使用 API Key 方式时不要每次都在登录界面粘贴更推荐把它配置成环境变量。Windows PowerShell 下执行$env:ANTHROPIC_API_KEY你的keymacOS / Linux 下执行export ANTHROPIC_API_KEY你的key这个设置只对当前终端窗口生效关闭后失效好处是不会留痕。想永久生效Windows 用户去“系统属性-环境变量”里新增macOS / Linux 用户把它写进~/.bashrc或~/.zshrc。如果你使用的是第三方兼容接口还需要设置 Base URL 环境变量export ANTHROPIC_BASE_URLhttps://你使用的服务地址登录成功后会进入一个带交互界面的终端会话能看到当前目录、模型信息和输入框。到这里Claude Code 的安装链路才算完整走通了。3.2 权限模式怎么选别一上来就“全自动”Claude Code 有权限体系这个设计很多人会忽略但它特别重要。因为 AI 要在你电脑上执行命令、修改文件如果什么都能干风险其实不小。它把权限分为几种级别默认情况下读文件通常不需要确认写文件和执行命令会弹确认提示你也可以通过ShiftTab在几个模式之间循环切换。我第一次用的时候图省事直接切成全自动模式结果 AI 自作主张往系统目录里写了几个配置文件后面排查了好一阵子。我的建议是开始阶段保持默认或“按需确认”模式明确看到每一条要跑的命令心里有数了再放它去执行。等熟悉了它的执行逻辑再对可信项目放宽权限。如果你跑的是一些高危命令比如删除文件、强制推送 Git、修改数据库结构务必在权限配置里把它们加入黑名单。这个习惯能救你很多次。3.3 前几个必须会的斜杠命令Claude Code 的交互除了直接输入自然语言还有一些常用的斜杠命令相当于快捷键。/help查看帮助文档不记得用法时随时调出/status查看当前任务状态和上下文占用情况/resume重新加载上次中断的会话/compact上下文太长时压缩历史记录/exit退出会话会话过程中如果你想让它停下来可以直接按Esc键中断当前步骤或者按CtrlC终止整个会话。中断后你可以重新描述需求Claude Code 会基于已有上下文继续工作。4. 代码实战让它替你写完一个批量图片压缩工具4.1 先花 10 分钟把需求定义清楚工具再好需求不清楚照样翻车。我见过很多用户给 AI 一句话“帮我写个图片处理工具”然后抱怨输出不可用。这不怪 AI需求太模糊它只能自由发挥。这里我选一个比较典型的实战场景批量图片压缩工具。需求描述可以是这个版本在 image-shrink 项目里实现一个 Python 命令行工具读取 input 目录下所有 jpg/png/webp 图片等比缩放到最长边不超过 1500px转成 webp 格式输出到 output 目录压缩质量设为 82并生成一张 JSON 报告记录每个文件压缩前后的体积变化。依赖只用 Pillow。我故意把输入目录、输出条件、格式、质量标准、依赖库都写清楚了。这样的需求一个普通程序员能实现Claude Code 也能实现而且交付偏差会小很多。4.2 把需求交给 Claude Code看它自己跑完整个流程先准备项目骨架mkdir image-shrink cd image-shrink claude然后在对话里粘贴你写好的需求。它会先梳理一下任务列出计划然后开始读目录、创建脚本文件、安装依赖、运行测试。这个过程中你会看到大量命令行输出比如创建script.py、执行pip install pillow、运行脚本查看结果非常像在看一个真人程序员远程操作你的电脑。如果这是你第一次用它写完整工具我建议你全程盯着执行过程。重点看两类信息一是它在执行哪些命令二是命令执行后的输出是否正常。比如它运行完脚本发现输出目录是空的就会自己去查原因大概率是源码里没处理目录创建逻辑然后立刻回滚修改。4.3 中途报错不用慌让它自己看日志修复AI 写代码不可能一次通过这和人类一样。遇到报错时你不需要自己分析日志直接把它输出的报错信息复述给它或者让它“读取当前报错并修复”。Claude Code 会查看具体报错内容结合上下文调整代码。有一次它生成的脚本因为 Pillow 没处理RGBA模式的 PNG 图片而报错我没插手只回了一句运行报错了把报错信息贴出来并修复注意处理 PNG 透明通道它立刻读取了 Python traceback定位到图片保存的代码补上了转换RGB模式的逻辑然后重新运行。这种“看到错误、分析错误、修复错误再验证”的闭环能力是 Claude Code 和传统代码生成工具最大的区别。不过有一点你要记住它修复时可能只针对当前报错做最小修补不一定顺带改掉其他潜在隐患。所以修复完成之后最好让它再跑一次边界测试比如空目录、超大图片、目标目录不存在这几类情况。4.4 人工验收AI 生成的代码必须过这 5 道关卡用 AI 写代码不代表可以闭眼收货人工验收是必须的。我每次都会按下面五个维度检查 AI 的产出依赖是否精简。它是不是往依赖清单里塞了根本用不到的库如果是要求它去掉。边界情况是否处理。输入目录不存在、图片损坏、文件名特殊字符这些情况会不会报错。路径是否硬编码。是不是把当前绝对路径写死进代码里换成别人电脑就会跑不起来。输出是否符合预期格式。报告字段完整吗日期格式统一吗命名规矩吗。是否有隐藏风险。有没有操作磁盘覆盖、递归删除、写入敏感位置的隐患。对新手来说最简单有效的方式是直接看改动文件的内容。你不一定每行都懂但至少能看懂大框架。如果有哪些部分完全看不懂让 Claude Code 解释一遍让它逐模块说明逻辑。这不仅是验收也是你学习 AI 生成代码思路的好机会。5. 从“能用”到“好用”把 Claude Code 调教成老员工5.1 写一张给 AI 的便利贴CLAUDE.mdClaude Code 支持读取一个叫CLAUDE.md的文件当作项目背景知识。每次启动会话时它会自动读取这个文件把里面的约定当作工作准则。这个文件相当于给 AI 的入职手册非常重要。在项目根目录新建CLAUDE.md写上简明规则# image-shrink 项目约定 ## 技术栈 - Python 3.11 Pillow - 命令入口python script.py ## 编码规范 - 所有路径必须通过 pathlib 处理禁止硬编码绝对路径 - 函数必须写 docstring - 依赖变更必须在 requirements.txt 中同步 ## 注意事项 - 不删除 input 目录下的原图 - 输出目录每次运行前自动清空有了这个文件后续你让 AI 加功能、改逻辑它会自觉遵守里面写的规则而不是每次重新发明一套风格。这个习惯特别适合团队项目一份CLAUDE.md全组共享AI 产出的代码风格会稳定很多。5.2 自定义命令把高频动作变成一句话如果你经常让 AI 做同一类事情比如代码审查、提交信息生成、写测试可以把它封装成自定义斜杠命令。在项目的.claude/commands/目录下建一个 Markdown 文件文件名就是命令名。比如创建.claude/commands/review.md你是一个严格的代码审查员。请逐文件检查本次变更涉及的代码重点关注 1. 是否有明显逻辑错误或死代码 2. 是否有安全隐患尤其文件路径、外部命令执行 3. 是否有不符合项目 CLAUDE.md 约定的地方 输出格式问题清单 严重程度 修改建议。然后你在会话里输入/review它就会自动按这套标准执行审查。同一项目里可以配置多个命令相当于给团队造了一组 AI 专属工具。5.3 settings 和权限的精调更精细的权限控制可以写在~/.claude/settings.json里。这个文件能定义哪些命令直接允许、哪些需要确认、哪些直接拒绝{ permissions: { allow: [Read, Bash(npm run test)], ask: [Write, Bash(pip install *), Bash(git add)], deny: [Bash(rm -rf *), Bash(git push), Bash(git reset --hard)] } }我个人强烈推荐把git push加到 deny 里。因为 AI 帮你把代码提交到本地仓库是一回事直接推送到远程是另一回事万一它推了一个有问题的版本上去影响面就不可控了。宁可多花 30 秒自己执行推送也别让它替你省这个事。5.4 配合 VS Code 一起用Claude Code 官方提供了 VS Code 扩展装上以后可以直接在编辑器侧边栏打开 Claude Code 面板。它的好处是能结合编辑器当前打开的文件上下文比如你在某个文件里选中一段代码可以直接让 AI 基于选中内容修改、重构或解释。不过我的实际体验是日常命令行版本的 Claude Code 才是核心VS Code 扩展更像是锦上添花。如果你重度依赖编辑器那装上没什么坏处如果你经常在服务器上操作命令行版本完全够用不需要装扩展。6. 国内环境最容易踩的坑一份问题排查速查表6.1 安装阶段npm 超时、命令找不到我见过最多的问题是npm install -g anthropic-ai/claude-code卡住或直接超时这通常是 npm 默认源在国内不稳定导致的。解法就是把 registry 切到国内镜像我前面讲过这里再强调一遍npm config set registry https://registry.npmmirror.com如果安装成功了但运行claude提示找不到命令基本可以确定是 npm 全局目录没有加入系统 PATH。先执行npm prefix -g拿到目录后把它加进环境变量。Windows 用户如果要立即生效记得重开终端窗口。6.2 API 网络链路问题登录不了、会话超时Claude Code 装好后卡在第一关“登录认证”或“请求不到模型”的人非常多。这里说明一个概念Claude Code 本身安装在国内没问题真正敏感的环节是模型 API 的访问链路。如果你的网络访问 Anthropic 官方接口确实不稳定最务实的办法是使用第三方兼容 API 服务。很多平台提供 Anthropic 兼容接口会给你一个 Base URL 和 Key你只需要设置两个环境变量export ANTHROPIC_API_KEY第三方给你的key export ANTHROPIC_BASE_URLhttps://第三方服务地址选择这类服务时我建议先问清楚四件事是不是官方原模型请求数据会不会被用于训练涉及数据隐私是否有并发和限流限制价格按什么口径计费。这四条能问到准踩坑概率会降低很多。另外无论你走官方还是第三方如果提示模型返回超时、频繁 429、响应特别慢先检查是不是本地网络质量波动再检查服务商的运行状态页。很多情况下不是 Claude Code 的锅。6.3 运行阶段鉴权过期、限流、上下文超长使用过程中常见的报错有这么几类。鉴权过期状态码 401 或提示invalid x-api-key。处理办法是重新生成 API Key并更新环境变量确认前后没有多余空格。限流状态码 429 或提示rate limit reached。多半是并发请求太多或者账号额度太低。把任务切小、降低并发或者升级账号额度。特别是在第三方服务上限流策略可能很严格遇到这种情况调整参数即可。上下文超长提示context exceeded或会话越来越笨。Claude Code 的上下文窗口是有限的长时间对话会把窗口塞满。这时按/compact压缩历史再继续或者干脆开一个新会话把当前的结论复制过去。模型突然失联提示连接重置、读取超时。先用浏览器测试一下 API 服务地址是否能正常返回排除网络波动再回到终端重试。6.4 权限提示频繁打扰怎么办默认权限模式下AI 每次写文件、装依赖都会弹出确认询问。做小项目还好做大型重构时会感觉像在给 AI“逐条签字”。我的做法是分两步先在项目settings.json里把明确安全的高频操作加进allow比如读取文件、运行测试再把危险操作加进deny。这样日常不会被打扰危险动作依然可控。如果你用的是第三方兼容 API还可能出现明明 Key 正确但控制台授权的模型列表为空之类的问题这时候直接回退到claude doctor诊断命令查一下配置它能帮你检查环境变量、登录状态和网络连通情况。最后分享一点我的个人使用体会这套工具我用了大半年如果你问我什么项目最适合上手我会说从自己熟悉的、规则明确的小任务开始。比如批量重命名文件、整理日志、写一次性脚本。这类任务需求清晰出错成本低试错空间大非常适合用来理解 Claude Code 的工作逻辑。不要一上来就让它重构一个大型老项目很容易失控体验也会很差。还有一件事我想认真提醒AI 写的代码就当它是一位能力很强但偶尔马虎的同事交上来的作业你必须审。尤其是涉及文件操作、数据库变更、远程推送这类影响面大的命令哪怕它表现得很自信也先看两眼再放行。我在实际操作中遇到过它把测试用例删了重新生成一套、把配置文件路径改了导致服务起不来等问题但因为我一直盯着权限和改动记录每次都能及时扭转局面。最后分享一个免费的小技巧让它解释它为什么这么写。你在对话里追问“这段代码为什么不用标准库自带的办法而是引入第三方依赖”它通常能讲出一套逻辑。这个过程对你提升代码设计能力和做技术决策都有帮助。Claude Code 不是替代你思考的工具它是放大你思考效率的工具这个定位想清楚了使用体验会完全不一样。