第一次完整配置好 Claude Code我前后花了大半个下午。这工具在开发者圈子里口碑已经攒得很高了但真要把它装好、跑通、用顺手总得跨几道坎。当时我照着官方文档装了 Node.js又装了 Git最后却卡在登录授权上——终端里授权一直不通过折腾半天才发现是 Node 版本太旧升级到 LTS 之后立刻就好了。后面又陆续踩过 PowerShell 执行策略、中文路径乱码、权限弹窗过多这些坑。所以这篇笔记我想把“从零到能用”的完整配置过程写下来给准备上手 Claude Code 的朋友省点时间。这篇文章会以一个全新的开发机为起点按环境准备、安装方式、登录认证、核心配置、问题排查的顺序展开。无论你是 Windows 11 还是 macOS无论你习惯纯命令行还是 VS Code 插件都可以照着操作。对于已经装过但用得不顺的同学重点看第 4 节和第 5 节基本能解决你八成以上的问题。1. 环境准备先把地基打牢1.1 Node.jsClaude Code 的运行基座Claude Code 官方主推的安装方式是基于 npm 包分发所以 Node.js 是整个工具链的第一块地基。虽然名字里带 Node但严格说它和前端开发关系不大你只需要把它当作一个跨平台的 JavaScript 运行时来装就行。版本方面官方要求 Node.js 18 及以上但我的建议是直接上 20 LTS 或 22 LTS。LTS 是长期维护版本bug 修复和新特性跟进都比较稳当用来跑这种长期使用的命令行工具最省心。太旧的版本不仅可能跑不起来还容易在登录授权、长会话这些环节出一些莫名其妙的问题。我之前就遇到过授权页面一直打不开的情况排查到最后才发现是 Node 版本太老导致回调处理异常。安装路径上Windows 用户直接去官网下载 LTS 安装包一路 Next 就行。注意安装在纯英文路径下不要有中文和空格否则后面容易踩坑。macOS 用户我习惯用 Homebrew一条命令搞定brew install node22安装完之后新开一个终端窗口分别执行下面两条命令确认版本node -v npm -v如果提示找不到命令大概率是安装时没有把 Node 的 bin 目录加入 PATH重装一遍并勾选添加到 PATH 的选项就好。这一步看起来简单但很多人后面遇到“claude 不是内部或外部命令”的问题根子就在这里。还有一个我比较推荐的做法用版本管理器来装 Node。Windows 下用 nvm-windowsmacOS 和 Linux 下用 nvm。好处是以后想切换 Node 版本、处理老项目兼容问题时不用重新卸载安装。配好 Claude Code 之后你会发现这个习惯在很多其他开发场景里同样能救你一命。1.2 Git不只是版本管理工具很多人觉得 Claude Code 是个 AI 工具和 Git 八竿子打不着。但实际用起来你会发现Git 几乎是它的“左膀右臂”。Claude Code 在项目里查看文件变更、生成提交信息、对比改动、撤销误操作全部依赖 Git 命令。如果你机器上没装 Git或者 Git 没进系统 PATHClaude Code 很多功能会直接报错。Windows 用户从 git-scm.com 下载安装包安装过程中有一个很关键的选项——“Adjusting your PATH environment”记得选第二项“Git from the command line and also from 3rd-party software”。这样 Claude Code 才能在终端里正常调用到 Git 命令。我见过有人图省事选第一项结果 Claude Code 跑 Git 操作时一直提示找不到命令。macOS 用户最简单的方式是执行xcode-select --install这条命令会安装苹果官方的 Command Line Tools里面自带了 Git。也可以用 Homebrew 装新版本brew install git装完之后先验证一下git --version接着做一次全局身份配置因为 Claude Code 在生成提交信息时需要读取 Git 的用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱这一步最好在配置 Claude Code 之前完成。我见过不少朋友 Claude Code 都装好了结果让它提交代码时一直报错查了半天才发现是 Git 身份信息缺失。CLAUDE.md 写得再细也顶不过基础环境缺一块。1.3 终端和编辑器顺手才能高效Claude Code 本质是个命令行工具终端的好坏直接影响使用体验。Windows 11 用户建议用 Windows Terminal配合 PowerShell 7 使用。系统自带的 cmd 虽然也能跑但字体渲染、快捷键、标签页管理都差一截。PowerShell 5.1 是 Windows 预装的老版本很多现代终端工具的兼容性都不如 PowerShell 7建议尽早升级。我自己在 Windows 上踩过的最深的坑就是旧版 PowerShell 对长路径和 UTF-8 的支持太差导致 Claude Code 输出格式乱掉。macOS 用户直接用系统自带的 Terminal 就能跑不过我更推荐 iTerm2分屏、搜索、主题配置都更舒服。Shell 方面 zsh 是默认选项配一个 oh-my-zsh 选个顺眼的主题代码看起来也舒服很多。编辑器方面如果你的主要开发环境是 VS Code那配合度确实是最高的。Claude Code 官方提供了 VS Code 插件安装后可以在编辑器里直接启动对话。但这里要提醒一句VS Code 插件底层仍然依赖命令行版 Claude Code所以无论你用不用插件第 2 节里的 CLI 安装都跑不掉。还有一个容易忽略的点改完环境变量之后已经打开的终端窗口不会自动更新必须新开一个窗口才能捞到最新配置。配置阶段频繁提示“找不到命令”时先别急着改系统把终端重开一下往往就解决了。2. 安装 Claude Code三种方式怎么选2.1 npm 全局安装最推荐的方式环境准备完毕接下来就是装 Claude Code 本体。我最推荐的方式是用 npm 全局安装命令只有一条npm install -g anthropic-ai/claude-code为什么推荐这个方式首先是可控性好安装、升级、卸载都走 npm 一套流程命令是标准的出问题也容易定位。其次是 npm 的生态成熟依赖处理、版本回退都比手动拷贝要可靠。安装完成后重开终端执行claude --version能输出版本号就说明基本装好了。这时直接在项目目录下执行claude就会进入交互式对话界面。第一次启动会进入登录引导这部分我放到第 3 节细说。之后升级也很简单npm update -g anthropic-ai/claude-code或者直接运行 Claude Code 自带的更新命令。如果想卸载执行npm uninstall -g anthropic-ai/claude-code还有一些团队会把anthropic-ai/claude-code写进项目的 devDependencies 里这样每个成员拉完代码后执行npm install就能自动装上统一版本的 Claude Code。这个做法在团队协作里很实用能避免你用的版本和同事不一样导致的兼容问题。2.2 官方安装脚本适合快速部署如果 npm 方式在网络或权限上受阻Anthropic 官方还提供了一条安装脚本curl -fsSL https://claude.ai/install.sh | bash这条命令会把 Claude Code 安装到用户目录下通常不需要管理员权限。对于 Linux 服务器、CI 环境这种需要快速部署的场景非常方便。但我在 Windows 上一般不建议走脚本因为 curl、bash 在 Windows 原生环境里并不总是可用。Windows 用户如果不想用 npm直接用第 2.3 节的 VS Code 插件方式会更省事。官方脚本安装的版本和 npm 来自同一个发布渠道所以功能上没有差异。只是这种安装方式在卸载时稍微麻烦一点需要手动清理安装目录和配置目录所以个人开发机我依然首推 npm。2.3 VS Code 插件版编辑器和 AI 协同搜索“claude code vscode”的朋友多半是想在编辑器里直接使用。这个需求很普遍官方也做了支持。在 VS Code 扩展市场里搜“Claude Code”看到 Anthropic 官方出的插件装好之后左侧活动栏会出现 Claude Code 的入口也可以在命令面板里输入相关命令打开。插件版的好处是能直接感知当前打开的文件、选中的代码片段省去你手动复制粘贴上下文的动作。插件使用之前一定要确认命令行版 Claude Code 已经装好。你可以先关掉 VS Code在系统终端里执行claude --version验证。如果命令提示找不到插件打开后大概率也是连不上的。我在实际使用中的体验是日常聊天式编程用插件窗口很顺手但涉及跑测试、改配置、批量操作文件时还是切回独立终端更自由。两种形态各有适用场景不是替代关系。2.4 Windows 和 macOS 的专属设置Windows 用户最容易踩的坑是 PowerShell 执行策略。默认策略可能会阻止 npm 安装的脚本运行表现为运行claude时提示“无法加载文件因为在此系统上禁止运行脚本”。解决办法是用管理员权限打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后按提示输入 Y 确认。这个命令只对当前用户生效不影响系统其他配置。不会改系统级策略所以安全性没问题。另外如果项目路径或用户名包含中文Claude Code 在读取文件路径时偶尔会出现显示问题。我建议开发项目的根目录尽量保持纯英文路径比如D:\Projects\my-app而不是D:\项目\应用。这属于环境层面的预防成本最低但能避免很多奇怪的小毛病。macOS 用户相对省心只要 Node 和 Git 装好基本一路通畅。唯一要注意的是如果你用了 Homebrew 安装的 Node而 npm 全局包的 bin 目录没进 PATH同样会遇到“claude 找不到”的问题。检查一下~/.zshrc里的 PATH 设置即可。3. 登录认证与首次启动3.1 账号登录流程第一次运行claude它会引导你完成登录认证。整个流程大概是这样终端会给出登录选项和一次性授权链接浏览器打开后登录账号、确认授权然后回到终端工具自动完成绑定。我在前面提到过这一环节如果卡住优先怀疑 Node 版本和网络环境。把 Node 升到 LTS 版本、确认网络环境正常之后再重新执行claude试试。别在旧版本上反复重试那是在浪费时间。遇到过一次就知道这种问题重试十次都没用根因不对怎么跑都是白搭。登录成功之后你会发现主目录下多了一个.claude目录这是它的配置总目录。Claude Code 的全局配置、会话记录、shell 快照等都在这里。这个目录对你的日常使用很重要后面几节很多配置都会往里面放。如果想确认当前登录状态可以用claude doctor它会把版本、Node、Git、配置目录、认证状态等关键信息一次列出来比肉眼排查高效得多。3.2 使用 API Key 的场景如果你在公司环境、CI 流程或团队自动化场景中使用 Claude Code账号登录可能不是最佳选择。更常见的做法是配置 API Key。方式是在系统环境变量里设置ANTHROPIC_API_KEY指向你申请的 API Key。Windows 可以在“系统属性 - 环境变量”里新增macOS 和 Linux 可以写到~/.zshrc或~/.bashrcexport ANTHROPIC_API_KEY你的API Key设置完成后重开终端再运行claude它会优先读取这个环境变量完成认证。这个方式的好处是全局生效不管在哪个项目目录下启动 Claude Code都能直接用。这里要着重提醒一句API Key 是敏感信息千万不要写进项目配置文件里更不要提交到 Git 仓库。我见过不止一个项目因为.env文件被误提交导致 Key 泄露。正确的做法是放在系统环境变量层或者你所在团队统一管理的密钥服务里。如果你把 Key 写到settings.json里那一定要确保这个文件不会跟着项目走。3.3 首次启动前的小检查正式进入配置之前我建议先跑一遍claude doctor。这个命令会检查环境完整性包括 Node 版本是否达标、Git 是否可用、配置目录是否正常、认证状态是否有效等。如果显示有红色告警或者提示项按它给的指引处理就好。大部分问题都出在 PATH 没配好、Node 版本过旧、Git 未安装这三类参考第 1、2 节的步骤补上即可。claude doctor这个习惯我建议保持下去。以后每次升级 Claude Code、或者从别的机器同步配置之后先跑一遍它能省掉很多“看起来一切正常但就是跑不起来”的排查时间。工具链这种东西出问题不可怕怕的是问题藏在你看不到的地方。4. 核心配置项把工具调教成自己人4.1 配置文件的位置和优先级Claude Code 的配置体系分三层理解这三层之后你就知道该把什么配置放哪里了。第一层是全局配置放在用户主目录下~/.claude/settings.json。所有项目有效适合放账号级别、通用规则类的配置比如常用的权限放行规则、默认模型等。第二层是项目级配置放在当前项目的.claude/settings.json。它会跟着项目走上传到 Git 后团队其他成员也能共享。适合放项目专属规则比如某些目录禁止修改、某些命令必须先经过确认。第三层是项目本地配置放在.claude/settings.local.json。这层配置不会提交到 Git适合放个人偏好和本机差异比如你的自定义环境变量。三层配置的优先级是项目本地配置 项目级配置 全局配置。也就是说同名配置项在低层级设置后会被高层级覆盖。这个规则理解起来和 CSS 层叠差不多。修改配置有两种方式一种是直接编辑上面的 JSON 文件另一种是用命令行claude config set -g 键名 值手动编辑文件其实也挺好但命令行的好处是会自己做格式校验不容易写出非法 JSON。个人建议新手优先用命令老手随意。我平时改配置文件比较多但每次改完都会顺手跑一下验证确保没把 JSON 结构写坏。4.2 权限配置放权与收权Claude Code 有一套权限体系决定了 AI 在执行操作前需不需要征求你的同意。这是它用起来“顺不顺手”的核心。默认情况下Claude Code 跑命令、改文件前都会弹出确认提示。对第一次使用的用户来说这个默认模式最安全但用多了确实烦人——改个文件还要确认一次效率很低。这时就可以在配置里放行高频操作。在~/.claude/settings.json里可以这样配置{ permissions: { allow: [ Read, Edit, Bash(npm run lint), Bash(git status) ], deny: [ Bash(rm -rf *), Write(.env) ] } }allow是自动放行的操作deny是永远禁止的操作ask可以设置哪些操作仍然需要询问。这个设计很合理你把信任边界画清楚AI 剩下的活就不用你操心了。实际配置时我有个建议刚开始用的时候把权限收敛一点只放行Read和Edit命令类操作保持询问。用熟了之后再逐步扩大到高频命令。别一上来就大开绿灯AI 目前还是容易出现意料之外的操作的。至少把rm -rf、格式化磁盘这类高危命令、以及.env这样的敏感文件写进deny里总是没错的。权限是一道安全线宁可前期烦一点也别拿生产数据去赌。4.3 CLAUDE.md项目级记忆文件这个是最值得花时间配置的部分我甚至愿意把它称为 Claude Code 的“入职培训手册”。CLAUDE.md 是 Claude Code 在项目中读取的说明文件放的位置有两种项目根目录./CLAUDE.md或者全局~/.claude/CLAUDE.md。项目级文件生效范围是当前项目全局文件对所有项目生效。它的写法本质上就是 Markdown核心是告诉 AI 这个项目“你是谁、怎么跑、有什么规矩”。比如这样# 项目说明 这是一个基于 Node.js 的 REST API 服务。 ## 常用命令 - 安装依赖npm install - 本地启动npm run dev - 跑测试npm test - 代码检查npm run lint ## 代码规范 - 所有接口返回统一格式{ code, message, data } - 日期时间一律使用 UTC 存储 - 新增 API 必须写 OpenAPI 文档 ## 注意事项 - 不要修改 src/config/production.js 中的密钥占位符 - 数据库迁移文件命名必须带时间戳前缀写好的 CLAUDE.md 有一个共同特点命令式、清单式、有明确边界。你在里面写的每一条规则AI 后续在项目里都会当成交付标准来执行。所以在里面塞“本项目很牛逼”“代码写得很好”这种废话没有意义信息密度越高AI 的行为就越贴合你的预期。我第一次意识到这个文件的重要性是让它改一个接口。它不知道项目的返回格式规范一顿操作把整个模块的 response 结构都改乱了。后来我把规范写进 CLAUDE.md再遇到类似需求它自动就会按统一格式输出。强烈建议每个项目都花十分钟维护这份文件。随着项目迭代里面还可以补充新的规范、常见注意事项AI 的上下文也会越来越“懂”这个项目。4.4 Skills 和 MCP扩展 AI 的能力边界Skills 是 Claude Code 的一种扩展能力类似给 AI 装“技能包”。社区里有不少现成的 Skills 可以直接用比如生成提交信息、审查代码、整理依赖等等。安装方式通常是把它放进项目的.claude/skills目录每个技能对应一个子目录里面有一个SKILL.md描述文件包含技能的名称、适用场景、调用方法。也可以去 Claude Code 的官方技能仓库找现成的来参考然后按需引入。MCPModel Context Protocol则是更底层的协议级扩展它让 Claude Code 可以连接外部工具和数据源比如操作数据库、调用第三方 API、读写外部系统。配置方式是在.mcp.json或通过claude mcp add命令添加。我的建议是新手阶段不用急着碰 MCP先把 CLAUDE.md 和权限配置做好工具基础体验已经能打 80 分。MCP 属于锦上添花适合有明确的外部系统对接需求时再上。而且 MCP 配置涉及外部系统地址和密钥复杂度比基础配置高一个量级等基础用熟了再研究也不迟。4.5 其他高频配置项速查除了权限和项目记忆还有几个配置项值得花几秒钟了解一下。model用来指定使用的模型。如果你对 Claude 的默认路由不满意或者团队有固定的模型要求可以在这里指定。实际使用时我一般不动它但如果你在多模型之间切换做对比测试这个配置会很有用。includeCoAuthoredBy设置为 true 时Claude Code 生成的提交信息会自动带上合作署名。团队协作时这个配置很有用可以方便追踪哪次提交是 AI 参与的。审计代码的时候就清楚多了。env可以在配置里注入环境变量。注意区分这个是工具运行时的环境变量和系统环境变量不一样适合在项目级配置里为特定项目预设值。比如某个项目的测试环境地址写在项目配置里比每个人各自设置系统变量要省事。statusLine控制 VS Code 状态栏显示的信息对用插件版的人比较实用。这些配置项的最终名字和可选值都要以官方最新文档为准因为工具迭代很快。我的经验是每次升级完 Claude Code翻一下claude config --help和官方文档的更新日志比网上搜一堆过时教程靠谱得多。5. 常见问题与排查技巧实录5.1 “claude 不是内部或外部命令”这个现象在 Windows 上最常出现。原因基本就两个npm 全局 bin 目录没进 PATH或者终端没重开。先用一句命令确认 npm 全局目录npm config get prefix然后把输出目录里的相关文件夹加到系统 PATH。如果不想折腾 PATH也可以直接卸载重装一遍 npm 包部分安装器会自动处理路径。重装完记得新开终端。macOS 上出现同样的问题多半是~/.zshrc里漏配了 npm 的全局 bin 路径。把路径加进去然后执行source ~/.zshrc让它立即生效。这个问题我在帮同事排查时遇到过好几次几乎每次都是这两个原因之一方法很固定。5.2 登录卡住、授权失败登录环节卡住最常见的三个原因Node 版本过旧、网络访问异常、浏览器没有正常完成授权回调。处理顺序建议是先升级 Node 到 LTS再跑一遍claude doctor看认证状态最后再试一次登录。注意浏览器授权成功后要回到终端看是否出现成功提示有些版本的流程需要手动回车确认。我自己的经历是卡住时在终端反复敲claude没有意义反而可能触发并发认证更乱。冷静下来按顺序排查基本十分钟内能定位。5.3 VS Code 插件连不上 CLIVS Code 插件打不开、白屏、一直转圈大概率是插件没找到命令行版 Claude Code。处理方式先打开系统终端执行claude --version确认命令行能跑然后完全退出 VS Code再重新打开。如果还不行检查 VS Code 的插件设置里CLI 路径是否被指定成了错误位置。这里有个容易忽略的点VS Code 启动时会继承启动它的终端环境变量。如果你改过 PATH 但没重开 VS Code插件内部是“看不到”新路径的。所以改完环境变量之后不只是终端要重开VS Code 也要完全重启。这个问题特别隐蔽因为你在 VS Code 里开个新终端能看到claude但插件进程用的还是旧环境。5.4 权限弹窗太频繁权限弹窗频繁是新手用 Claude Code 时抱怨最多的点。解决思路不是直接跳过权限检查而是把高频操作写进permissions.allow。比如你经常让它跑npm test那就把Bash(npm test)放进允许列表。操作粒度可以很细既不影响安全性又能明显减少干扰。如果你只是临时想跑一次不打断的会话可以用启动参数切到更低干扰的模式。但那种全局跳过权限检查的方式我不建议作为日常使用。权限弹窗虽然烦但它本质是一道安全网等 AI 开始批量改文件时你会庆幸有这道网在。我见过有人为了省事全局跳过权限结果 AI 一气呵成把一堆不该动的文件全改了回滚回来心疼到不行。5.5 乱码、路径、环境变量问题Windows 终端出现中文乱码先尝试在终端里执行chcp 65001把代码页切到 UTF-8。如果每次都要手动切可以在 PowerShell 配置文件里固定下来或者在系统“区域设置”里勾选“使用 Unicode UTF-8 提供全球语言支持”。项目路径包含中文导致工具行为异常还是那句话把项目放在纯英文路径下一劳永逸。环境变量相关的疑难杂症比如配置了 API Key 却不起作用记得先确认环境变量作用范围。系统环境变量设置后新终端才生效当前终端临时设置的也只对当前终端有效。还有一个常见坑是我在改~/.zshrc之后忘记source导致新配置一直不起效白白折腾了十几分钟。我把常见问题整理成一张速查表方便你直接对照排查问题现象常见原因处理办法claude命令找不到npm bin 未入 PATH终端未重开检查npm config get prefix补 PATH 后重开终端登录授权一直不通过Node 版本过旧网络环境异常升级 Node LTS跑claude doctor检查VS Code 插件连不上CLI 没装好VS Code 未重启先确认 CLI 可运行重启 VS Code权限确认弹窗太多allow 列表配置不足把高频命令加进permissions.allow中文输出乱码终端编码不是 UTF-8执行chcp 65001或改系统区域设置项目路径中文导致异常路径含非 ASCII 字符项目移到纯英文路径修改配置不生效层级覆盖或 JSON 格式错误检查三层配置优先级用claude config修改npm 安装超时或卡死网络波动、npm 缓存异常清理 npm 缓存后重试这个表基本覆盖了我见到的大多数“配好了但用着难受”的问题。如果你遇到的是表格之外的问题还有一个笨办法但很有效把~/.claude目录备份之后整个删掉重新走一遍登录让工具重新生成默认配置。多数场景下重置一次比瞎改半天更省时间。最后分享一点个人体会。Claude Code 这类 AI 编码工具的配置很像给新同事做入职培训环境依赖是工位设备登录认证是门禁卡CLAUDE.md 是岗位手册权限配置是授权范围。花一两个小时把这几样理顺后面用起来会顺很多。我在真实项目里最大的感受是CLAUDE.md 的投入产出比是最高的。你花十分钟写清楚项目规范之后 AI 生成的每一步代码都会按照这个规范来省下的返工时间远不止十分钟。另外别忽视claude doctor每次升级完先跑一圈顺手清掉失效配置能帮你避开很多玄学问题。工具配好了后面剩下的就是多用、多调。Skills 和 MCP 这些扩展能力等你熟悉了基础会话模式之后再逐步加上会比你一上来全部堆满更有效率。等你用顺了再去做二次开发、接进自己的工程化流程就是水到渠成的事。