Claude Code 安装配置全指南：从零开始在终端中运行 AI 编程助手-平芜编程栈

1. 为什么现在该装 Claude Code，以及它到底解决什么问题

先别急着复制粘贴命令。我在本地正式把 Claude Code 用起来之前，其实已经围观它很久了。最早是在几个技术社群里看到有人贴终端截图，说用 Claude 直接在命令行里改代码、跑测试、查报错，我当时的第一反应是：这不就是把 ChatGPT 塞进终端吗？后来自己动手配完、跑了几个真实项目之后才发现，这玩意儿和聊天气泡完全是两码事。

Claude Code 是 Anthropic 官方推出的命令行 AI 编程工具，它的工作方式和你在网页对话框里粘贴代码、再复制结果回来完全是两个思路。它运行在你的开发机终端里，能够直接读取你的项目文件、理解你当前这个 Git 仓库的结构、搜索文件内容、在终端里执行命令、跑测试，甚至帮你提 PR。一句话概括：它不是一个“问答机器人”，而是一个“能干活的队友”。你给它一个任务，比如“帮我把登录接口加上参数校验”，它会自己读相关文件、改代码、跑 lint、执行测试，然后把改动结果列给你看。这个过程是在你的本地环境里完成的，不是把代码贴到某个网页上去，改动是真实落在你项目里的。

之所以我建议每个认真写代码的人都装一个，核心理由是三个：

它能把“打开编辑器、搜索文件、逐行阅读上下文、再开始改”这整段操作压缩成一句自然语言。对于老代码库、没文档的历史项目，这个价值尤其明显。
它操作的是真实的命令行环境。你可以让它读日志、跑测试、执行构建脚本，它基于终端输出做下一步判断——这是纯聊天工具做不到的。
它是 CLI 工具，这就意味着它天然适合和 VS Code、Cursor、JetBrains 这些编辑器配合，也可以直接跑在服务器上。不需要迁移你现有的开发工具链，门槛其实比想象中低。

这篇文章我默认你是第一次接触 Claude Code，从零开始，按顺序走完整个安装和配置流程。我会把每一类系统上的安装方式都写清楚，包含踩坑点、环境变量配置、初始化登录、权限边界设置，以及工具装完之后真正影响使用体验的细节调整。全程具体的命令、配置项我都会给出来，照抄就能跑通。

2. 安装前置条件：你的机器需要提前准备哪些东西

很多人在 Claude Code 安装过程中卡住的第一个地方，根本不是 Claude Code 本身，而是机器上的基础环境不齐。所以先把前置条件捋清楚，再进入安装环节。

2.1 操作系统与硬件要求

Claude Code 官方支持 macOS、Linux、Windows，但三者的体验从安装到使用有一些差别，先做个对比：

操作系统	安装难度	使用体验	特殊说明
macOS	低	最佳	原生支持，Terminal 直接跑
Linux	低	最佳	适合配合远程开发、服务器使用
Windows	中等	良好	推荐用 WSL 方式，原生 PowerShell 环境有已知坑

硬件上没有太高门槛，日常开发机就行。因为 Claude Code 本身是调用云端算力，复杂计算发生在服务端，本地只负责终端的输入输出和文件读写。真正吃资源的是你打开的项目本身——比如一个大型 monorepo 仓库，IDE 索引和 Claude Code 的搜索操作叠加，内存压力会上去。我建议开发机至少 16GB 内存，8GB 会比较吃紧，打开两个大项目再跑编辑器会很吃力。

2.2 Node.js 版本要求与安装

Claude Code 目前通过 npm 分发，Node.js 是必须装的。官方要求 Node.js 18 以上版本，我实测下来推荐用 20 LTS 或 22 LTS 版本，稳定性比奇数版本号靠谱得多。

如果你机器上还没有 Node.js，我建议优先用 nvm（Node Version Manager）来安装，而不是直接去官网下载安装包。原因是日常开发中你大概率会同时涉及多个项目，不同项目的 Node 版本要求不一样，用 nvm 可以随时切换版本，避免因为版本不匹配导致各种莫名其妙的编译错误。

macOS 和 Linux 下的安装方式一致。打开终端，执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后，重开一个终端窗口，或者执行source ~/.zshrc（Linux 用户可能是source ~/.bashrc）让 nvm 命令生效，然后验证：

nvm --version

接着安装最新的一版 Node.js LTS：

nvm install --lts nvm use --lts

最后确认一下版本号，只要主版本号大于等于 18 就没问题：

node -v npm -v

Windows 用户如果不想用 WSL，可以直接去 Node.js 官网下载 Windows 安装包。但我必须要提醒一句：Claude Code 在 Windows 上有一个非常常见的坑——它依赖 bash 环境来执行部分脚本命令，纯 PowerShell 环境下部分功能（比如某些 shell 工具调用）会报错。如果你目前主力就是 Windows，最稳的方案是安装 WSL2，然后在 Ubuntu 子系统里跑 Claude Code。网络上很多“Claude Code powershell 安装报错”的求助帖，基本都是没有走 WSL 导致的。

2.3 Git 与代码仓库的准备

Claude Code 和 Git 的集成是它的核心体验之一。它能自动感知当前分支、显示 diff、帮你生成符合规范的 commit message，这些都是通过读取 Git 仓库信息完成的。如果你的机器还没有装 Git，需要先装好：

# macOS 用户 brew install git # Linux 用户，以 Ubuntu 为例 sudo apt update && sudo apt install git -y # Windows 用户可以使用 Git for Windows，或者 WSL 里安装

装完之后配置基础的用户信息，这个不配置的话后面 Claude Code 生成的提交信息会没法签名：

git config --global user.name "你的名字" git config --global user.email "你的邮箱@example.com"

然后验证：

git --version

需要注意的是，Claude Code 的最强形态是在一个 Git 仓库内运行时产生的——它能追踪文件变动、知道自己改了什么、可以把修改前后对比提交上去。如果你是随便建个文件夹就开始用，功能会大打折扣。所以我建议你在跑 Claude Code 之前，先确保工作目录是已经初始化的 Git 仓库。如果项目还没有初始化，可以先执行：

git init

2.4 为什么安装失败时要先怀疑 Node.js 和 npm 镜像源

这里分享一个真实踩坑经验。安装 Claude Code 失败最常见的原因不是 Claude Code 本身的问题，而是 npm 包下载被阻断或者镜像源不完整。国内环境的读者大概率需要切换 npm 镜像源，否则npm install -g @anthropic-ai/claude-code可能会在下载阶段卡死，或者报常见的网络超时错误。

切换镜像源的方法是：

npm config set registry https://registry.npmmirror.com

验证是否生效：

npm config get registry

切换之后，安装速度会有质的提升。但要注意一点：切换到 npmmirror 后，如果你发布过 npm 包或者有私有包依赖，记得在对应的项目里单独维护.npmrc文件来指定官方源或私有源，避免全局配置影响发布操作。我自己是全局用 npmmirror、项目级用官方源来处理这个矛盾的。

3. 正式安装 Claude Code：三种方式按需选

前置环境准备好之后，正式安装其实就很快了。官方提供了三种安装途径，我按推荐度排序逐一说明。

3.1 方式一：npm 全局安装（最推荐）

npm 全局安装是官方默认推荐的安装方式，最大的好处是跨平台一致、升级简单、用 nvm 能同时管理多个版本。

打开终端，直接执行：

npm install -g @anthropic-ai/claude-code

等待安装完成，执行版本验证：

claude --version

如果能正常输出版本号，说明安装成功了。npm 会把claude这个命令链接到全局 bin 目录下，后续在任意项目的终端里输入claude都能启动。

升级方式也很简单，官方提供了一个内置的更新命令：

claude update

这个命令会自动拉取最新版本并完成替换，不用你再手动重新执行 npm install。

3.2 方式二：原生安装脚本（macOS / Linux）

如果你不想经过 npm，官方还提供了一个原生安装脚本，适合在 macOS 和 Linux 上使用：

curl -fsSL https://claude.ai/install.sh | bash

这个脚本会自动检测系统架构，下载对应平台的二进制文件并安装到用户目录下。装完之后的验证方式同样是：

claude --version

原生安装和 npm 安装在使用上没有任何区别，只是底层安装路径不同。我个人还是建议统一用 npm 管理，因为后续通过npm update -g @anthropic-ai/claude-code也可以完成升级，多一条更新的路。

3.3 方式三：在 VS Code 中集成运行（Windows 用户友好方案）

如果你是在 Windows 上，且暂时不想折腾 WSL，可以先把 Claude Code 作为 VS Code 插件来用。在 VS Code 扩展商店里搜索“Claude Code”，安装官方扩展后，在编辑器里直接打开终端面板，输入claude就可以启动。这个方式的本质还是调用本地 Node.js 运行时，只是省了 PowerShell 环境兼容性这一层问题。它和独立终端跑 Claude Code 没有区别，我个人在 Windows 机器上的体验是：VS Code 嵌入式终端比裸 PowerShell 稳定不少，至少不会遇到某些字体、编码导致的输出乱码问题。

不过还是那句话，Windows 用户如果要长期重度使用，WSL2 才是最稳的底盘。VS Code 插件方式可以作为一个快速体验入口，但不要把它当成最终形态。

3.4 安装完成后怎么确认环境是好的

很多新手安装完成后直接输入claude启动，然后卡在登录或者权限环节，误以为安装失败了。这里我提供一个 30 秒快速自检流程：

# 1. 确认 Node 环境 node -v # 2. 确认 npm 全局包列表里存在 Claude Code npm ls -g @anthropic-ai/claude-code # 3. 确认命令可执行 which claude # 4. 确认版本号 claude --version

这四步全部通过，说明安装这个环节已经结束，下一步进入初始化配置。

4. 初始化配置：登录、目录权限和第一个对话

安装好只是第一步，真正决定你能否顺利把 Claude Code 用起来的，是初始化配置这一环。很多教程把这部分一笔带过，但实际踩坑的人一大把。

4.1 首次启动与登录账号

在项目目录下输入：

claude

首次运行会出现一段欢迎提示，然后引导你登录。目前的登录方式是浏览器授权：终端会输出一个https://claude.ai/login?action=...这样的链接，复制到浏览器打开，登录你的 Claude 账号，然后回到终端，授权就完成了。

这个环节最常见的报错场景是“your organization has disabled claude subscription access for claude code”。如果你碰到这个提示，说明你的 Claude 账号是企业订阅，而企业管理员在后台关闭了 Claude Code 的访问权限。这个不是安装能解决的问题，要么联系管理员开启权限，要么使用个人订阅账号。

登录成功之后，你会进入一个交互式命令行界面，类似终端里的 REPL，输入/help可以看到常用命令列表，直接输入你的问题或者需求就能开始对话。

4.2 权限确认模式：学会先让它“问”再让它“动”

Claude Code 的一大特点就是它能直接在你的机器上执行命令、读写文件。所以它在真正执行敏感操作之前，会弹出确认请求，让你选择允许（Allow）还是拒绝（Deny）。

初次使用时，我强烈建议你保持默认的权限确认模式，不要为了图省事直接执行/permissions里预设的允许所有。你要理解一件事：Claude Code 运行在你本地，有权限读你的文件、执行命令、甚至提交代码，这个权限边界如果一开始就不设好，后面很容易出问题。我不是说它会做什么坏事，但代码生成的不可控性客观存在，让它每做一步都先跟你确认，你才有机会审视它正在做什么。

等你对它的执行逻辑足够熟悉、并建立足够的信任后，再考虑放开权限，或者通过配置文件维护一份固定的“允许命令白名单”。

4.3 MCP 配置：扩展 Claude Code 能力的钥匙

MCP（Model Context Protocol）是 Claude Code 实现外部能力接入的核心协议。简单理解：MCP 服务器就是一块 USB 接口，插上不同的外设，Claude Code 就能获得对应的能力。比如接入 GitHub 的 MCP 服务器，它就能直接操作你的仓库、创建 Issue、管理 PR；接入数据库 MCP，它就能直接查询你的业务表结构。

配置 MCP 的方式是编辑配置文件。运行：

claude mcp init

或者直接手动编辑位于~/.claude.json的配置文件，添加对应的 MCP 服务器地址和认证信息。我个人建议初学者在第一周先不要碰 MCP，先把 Claude Code 的原生能力用好——文件读写、git 操作、命令执行这些已经覆盖了日常大部分需求。等你对它的工作边界有感觉了，再按需接入 MCP，否则排错时你会分不清是 Claude Code 本身的问题还是 MCP 服务器的问题。

5. 编辑器整合与日常使用配置

Claude Code 作为命令行工具，其全能力集中在终端里。但对于大多数习惯了图形界面的开发者，把它融入编辑器工作流才是真实的使用场景。这节里我把 VS Code 的整合方式、Cline 插件的配合，以及几个实用进阶配置一次说清楚。

5.1 在 VS Code 中打开集成终端使用 Claude Code

最轻量、零成本的做法是：在 VS Code 里按 Ctrl+` 打开集成终端，然后输入claude启动。这样你在编辑器中选中文件、查看报错时，旁边的终端里直接和 Claude Code 对话，它读取的就是当前这个项目的上下文。光标定位在文件某一行的时候，Claude Code 能感知到你正在编辑的代码片段，这比“复制粘贴到网页”高效太多。

一个我平时用得比较多的技巧是：把 Claude Code 和 VS Code 的“源代码管理”面板配合使用。Claude Code 改完代码之后，Git 面板里会直接显示改动过的文件列表和 diff，你可以逐行审阅 Claude Code 的改动，再决定是否接受。我用下来，把“AI 改代码”和“人工 review”这两步严格分开，是质量最稳的做法。

5.2 用 Cline 插件在编辑器侧边栏里跑 Claude Code

Cline 是一个第三方 VS Code 插件，它把 Claude Code 的能力以侧边栏面板的形式嵌入编辑器。它最大的价值是可视化——你可以看到 Claude Code 每一步在做什么、经过了多少轮工具调用、每个文件的改动 diff 是什么样的，而不像纯终端那样只能看到一行行文本输出。

安装方式：VS Code 扩展商店里搜索“Cline”，安装后侧边栏会出现对应图标。在设置里配置 API 密钥或者选择接入方式，即可在编辑器内直接对话。

这个方式适合两类人：一是不习惯纯终端的初学者，可视化的操作反馈降低了上手门槛；二是需要审阅 AI 工作过程的人——Cline 把每个步骤都展开了，方便你确认它有没有偏离你的要求。

5.3 Claude Code 与 DeepSeek 的接入

在实际开发里，很多人会遇到一个现实问题：Claude 官方 API 调用成本偏高，而个人开发者希望在体验 Claude Code 工作流的同时，把模型切换成成本更低的替代模型。这时候可以通过配置模型的接入方式，让 Claude Code 调用 DeepSeek 等模型的接口，从而显著降低 token 费用。

具体做法是：修改 Claude Code 的配置（~/.claude/settings.json），添加自定义的模型接入配置，指定 API 地址、API Key 和模型名称。在网络上能搜到许多“claude code接入deepseek”的配置教程，核心都是围绕修改配置指向 DeepSeek API。

需要提醒的是，Claude Code 的部分高级特性（比如某些系统级工具调用）依赖官方模型的原生支持，切换到 DeepSeek 后，这些特性的稳定性会有折扣。我的建议是：日常简单任务、成本敏感场景可以用 DeepSeek 兜底，遇到复杂重构、代码审查这类高质量需求时切回官方模型。以下是我在实践中验证过的配置片段：

{ "apiBaseUrl": "https://api.deepseek.com", "apiKey": "你的DeepSeek API Key", "model": "deepseek-chat" }

这段配置的核心作用是让 Claude Code 在发起模型请求时，把请求路由到 DeepSeek 的 API 服务，而不是默认的 Anthropic API。字段apiBaseUrl指定了请求的目标地址，apiKey用于鉴权，model指定了具体调用的模型型号。DeepSeek 还提供deepseek-reasoner这类推理增强模型，如果你需要它先思考再回答，可以按需切换。

5.4 省 token 的几个实用习惯

“claude code如何用省token”这类搜索热度在社区里一直很高，说明大家用起来之后的第一个痛点就是费用。根据我的经验，省 token 的核心原则不是“少用它”，而是“让它少看无关东西”。以下是几个直接有效的做法：

启动时用--ignore参数指定忽略目录，不让它去扫描node_modules、dist这类庞大的生成目录。Claude Code 每次读取文件都是有代价的，别让它把时间花在垃圾文件上。
用/clear及时清空对话上下文。每个任务做完了就清场，不要在一个会话里堆十几个不相关的任务，上下文越长，后续每轮 token 消耗越夸张。
在提问时主动指定文件路径，比如“请只读取src/utils/auth.js和src/api/login.js这两个文件来分析登录问题”，它会严格按照你的范围执行，而不是全仓库扫描。
利用技能（Skills）功能，把一些重复性的、固定的分析流程做成模板。比如“每次处理报错时，先读日志、再查对应模块、最后给结论”这个固定流程，你可以配置成技能，省去每次重复描述的长文本。

5.5 用 Skills 固化高频工作流

Claude Code 的 Skills 功能本质上是一条“预定义的指令模板”。它允许你编写一套提示词和规则，把某项固定任务的操作路径固化下来。

官方文档里对 Skills 的定位是：服务于特定任务场景的指令集合，它可以包含背景说明、使用约束、输出格式等结构化内容。举个例子，你可以创建一个叫code-review的技能，让它每次执行时都遵循：

先读取当前分支的 diff，确定改动的文件清单。
再逐文件检查，重点看安全性、异常处理和代码风格。
最后按固定格式输出 review 结论。

创建方式：在.claude/skills/目录下新建一个子目录，里面放一个SKILL.md文件，按规范格式编写指令内容，然后在对话中通过@技能名触发。这个能力对需要固定输出格式的团队尤其有用——团队成员都能用同一套标准和口径让 AI 干活，代码 review 的粒度、报错处理的步骤都统一起来，避免每个人让 AI 干活的方式千差万别，导致产出质量参差不齐。

6. 安装和启动之后的高频报错及排查路径

这部分内容是我最想写给初学者的。社区里大家反馈最多的坑，其实就那么几个，但每个都足以劝退一批人。我按真实出现频率从高到低整理，并给出我认为最有效的排查顺序。

6.1 PowerShell 环境下安装或启动报错

在 Windows 的纯 PowerShell 环境里安装或运行 Claude Code，遇到报错是非常常见的。典型表现有：npm 安装成功但claude命令无法识别，或者启动时报spawn bash ENOENT之类的错误。

根因在于：Claude Code 的部分工具调用依赖 bash 或 sh 环境，而 Windows 本地的 PowerShell 和 CMD 并不天然提供这些环境。网上大量“Claude Code powershell 安装报错”的搜索结果都指向这个问题。

我的建议是：Windows 用户直接装 WSL2，在 Ubuntu 环境里跑 Claude Code，这是一劳永逸的解决方案。如果你只是临时试一下，可以在 PowerShell 里安装 Git for Windows（它自带了 bash 环境），然后把 Git 的 bash 所在路径加到系统环境变量里，部分报错能缓解，但仍然是治标不治本，时间长了会遇到各种奇怪的问题。

对比一下三条方案的取舍：

方案	安装成本	长期稳定性	适用场景
WSL2 + Claude Code	中等	高	主线开发，推荐
VS Code 扩展	低	中	快速体验、轻度使用
PowerShell 直接跑	低	低	不推荐

6.2 安装超时或卡在下载阶段

npm 安装过程中长时间没有进度，或者直接报网络错误，大概率是网络链路问题。最有效的处理方案就是前文提到的切换 npm 镜像源。如果你已经切换过还是卡，可以再确认一下是否安装了代理工具导致 npm 走了异常路径。

有时候问题出在 npm 缓存上——历史遗留的损坏缓存会莫名其妙地导致安装失败。可以执行：

npm cache clean --force

然后重新安装。这条命令会删除本地 npm 的所有缓存数据，虽然耗时一点，但能排除缓存损坏的干扰。

6.3 登录无法完成或授权失败

登录环节的授权失败，通常表现为：浏览器里成功登录了，但终端没有反应，或者提示授权失败。

排查步骤依次是：

确认浏览器里登录的账号和订阅类型是否支持 Claude Code。个人订阅（Pro/Max）都没问题，企业订阅要看管理员有没有开放权限。
确认终端网络环境正常，授权回调需要能够访问外网服务。
重新在终端执行claude时，如果不小心选了自动跳转而没有剪贴板链接，可以用重启命令重新触发登录流程：claude启动后输入/login，重新走一遍授权。

6.4 权限不足报错 Permission Denied

在 Linux 或者 WSL 环境下，偶尔会遇到权限不足的报错。原因在于 npm 全局安装目录需要写入权限，而用户没有该目录的写权限。一个常见的错误做法是用sudo npm install -g来强行安装，这样虽然能装上，但后续会导致各种文件权限混乱。

更规范的做法是：手动修正用户对 npm 全局目录的所有权。

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global

然后把~/.npm-global/bin添加到 PATH 环境变量（写入~/.bashrc或~/.zshrc），重开终端后再重新安装 Claude Code。这样整个链路上，所有文件都归属于当前用户，不会再因为权限问题产生后续连锁报错。

7. 初始化配置一处就够用的极简设置

我在实际操作中的体会是：Claude Code 的默认配置其实已经足够好用，新手不需要在配置阶段过度投入。很多人装好之后第一件事就是看各种进阶配置教程，其实没太大必要。先把基础跑通，用两周时间在真实项目里感受它的工作方式，之后再逐步微调配置，效率反而更高。

以下是我认为一个初学者最有价值的极简初始化设置：

{ "permissions": { "allow": ["Bash(npm run *)", "Bash(git *)", "Read(**)"] } }

这段配置的作用是：允许 Claude Code 直接执行所有 npm run 脚本、所有 git 命令，以及读取任意路径的文件。这三类操作覆盖了日常开发中最核心的低风险操作，可以减少大量确认弹窗的打断。它不包含写文件权限和任意 shell 命令权限，所以敏感操作仍会经过你的确认。

配置文件的路径根据系统不同略有差异：

macOS/Linux：~/.claude/settings.json
Windows：%USERPROFILE%\.claude\settings.json

注意：Bash(npm run *)这类声明只在命令匹配度极高时才自动放行。如果你运行的是npm run dev，它能直接通过；但如果你手动执行npm install，它不在规则内，依然会弹确认。这种“部分放行”的模式在安全性和便利性之间取了中间值。

最后再分享一个小技巧。Claude Code 的输出默认是全彩色高亮，在某些终端主题下面会显得刺眼。你可以在启动时加--output-format text参数切换为纯文本输出，或者在配置文件里设置"pretty": false，在颜色和可读性之间找到适合自己的平衡点。这个小设置不算核心功能，但长期使用下来，它对眼睛的友好度提升是实打实的。