Claude Code 从零到能用：环境准备、安装配置与常见问题排查全指南

第一次完整配置好 Claude Code，我前后花了大半个下午。这工具在开发者圈子里口碑已经攒得很高了，但真要把它装好、跑通、用顺手，总得跨几道坎。当时我照着官方文档装了 Node.js，又装了 Git，最后却卡在登录授权上——终端里授权一直不通过，折腾半天才发现是 Node 版本太旧，升级到 LTS 之后立刻就好了。后面又陆续踩过 PowerShell 执行策略、中文路径乱码、权限弹窗过多这些坑。所以这篇笔记我想把“从零到能用”的完整配置过程写下来，给准备上手 Claude Code 的朋友省点时间。

这篇文章会以一个全新的开发机为起点，按环境准备、安装方式、登录认证、核心配置、问题排查的顺序展开。无论你是 Windows 11 还是 macOS，无论你习惯纯命令行还是 VS Code 插件，都可以照着操作。对于已经装过但用得不顺的同学，重点看第 4 节和第 5 节，基本能解决你八成以上的问题。

1. 环境准备：先把地基打牢

1.1 Node.js：Claude 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 node@22

安装完之后，新开一个终端窗口，分别执行下面两条命令确认版本：

node -v npm -v

如果提示找不到命令，大概率是安装时没有把 Node 的 bin 目录加入 PATH，重装一遍并勾选添加到 PATH 的选项就好。这一步看起来简单，但很多人后面遇到“claude 不是内部或外部命令”的问题，根子就在这里。

还有一个我比较推荐的做法：用版本管理器来装 Node。Windows 下用 nvm-windows，macOS 和 Linux 下用 nvm。好处是以后想切换 Node 版本、处理老项目兼容问题时，不用重新卸载安装。配好 Claude Code 之后，你会发现这个习惯在很多其他开发场景里同样能救你一命。

1.2 Git：不只是版本管理工具

很多人觉得 Claude Code 是个 AI 工具，和 Git 八竿子打不着。但实际用起来你会发现，Git 几乎是它的“左膀右臂”。Claude Code 在项目里查看文件变更、生成提交信息、对比改动、撤销误操作，全部依赖 Git 命令。如果你机器上没装 Git，或者 Git 没进系统 PATH，Claude 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或~/.bashrc：

export 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 的官方技能仓库找现成的来参考，然后按需引入。

MCP（Model 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 插件连不上 CLI

VS 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目录备份之后整个删掉，重新走一遍登录，让工具重新生成默认配置。多数场景下，重置一次比瞎改半天更省时间。

最后分享一点个人体会。Claude Code 这类 AI 编码工具的配置，很像给新同事做入职培训：环境依赖是工位设备，登录认证是门禁卡，CLAUDE.md 是岗位手册，权限配置是授权范围。花一两个小时把这几样理顺，后面用起来会顺很多。

我在真实项目里最大的感受是，CLAUDE.md 的投入产出比是最高的。你花十分钟写清楚项目规范，之后 AI 生成的每一步代码都会按照这个规范来，省下的返工时间远不止十分钟。另外别忽视claude doctor，每次升级完先跑一圈，顺手清掉失效配置，能帮你避开很多玄学问题。

工具配好了，后面剩下的就是多用、多调。Skills 和 MCP 这些扩展能力，等你熟悉了基础会话模式之后再逐步加上，会比你一上来全部堆满更有效率。等你用顺了，再去做二次开发、接进自己的工程化流程，就是水到渠成的事。