Claude Code零基础安装指南：环境自检与常见报错全解析

先别急着复制安装命令。我知道你现在很兴奋，想赶紧把 Claude Code 跑起来，但绝大多数人第一次装完、兴冲冲敲下 claude，看到的不是对话界面，而是一整屏红色报错，然后开始怀疑人生：“是不是我电脑有问题？”“是不是要开什么特殊网络？”“是不是这个工具根本不支持 Windows？”

都不是。通常只有一个原因：你跳过了安装之后最不起眼、但价值最高的那一步——环境自检。这一步耗时大约 2 分钟，却决定了后面 28 分钟是丝滑复现还是反复踩坑。这篇东西就是写给零基础用户的，全程跟着操作，不求你懂什么底层原理，只求 30 分钟内让 Claude Code 在你自己的电脑上真正能跑起来，并且把那些 90% 的人会遇到但没人提前讲的坑，一次填平。

1. 装 Claude Code 之前，先搞清楚你要装的到底是个什么

1.1 它不是网页版，也不是 App，而是一个“住在终端里的程序员”

Claude Code 本质上是一个命令行工具（CLI），它运行在你的终端窗口里，不做图形界面，不弹漂亮窗口，而是通过文字跟你对话。你告诉它“帮我看下这个项目里哪里导致内存泄漏”，它会自己读代码、定位问题、给出修改建议，甚至直接帮你改。

把它理解成一个“住在终端里的程序员”就好——你在浏览器里用 Claude 聊天，是一问一答的顾问模式；而在 Claude Code 里工作，它直接接触到你的项目文件、代码目录和 Git 状态，像同事一样上手干活。

这也就解释了为什么很多教程强调“要在一个项目文件夹里启动它”。它需要上下文，不只是一个聊天框。

1.2 零基础用户的 30 分钟路线图

既然是零基础，我先把完整的行动链路给你列出来，每一段分别干什么心里有数：

1. 装 Node.js（Claude Code 的运行底座）
2. 做环境自检（这是大多数人跳过的步骤，后面详说）
3. 执行一条全局安装命令
4. 验证安装是否成功
5. 配置密钥或登录授权
6. 在 VS Code 里跑通一次真实对话

前两步是铺垫，真正的安装命令只有一条，剩下的时间主要花在“让电脑认识这条命令”和“让这个工具连上模型”上。

为什么强调零基础用户必须在终端里操作？因为 CLI 工具不像普通软件有安装包，点两下就完事。它需要系统里预先存在几个基础组件，而且这些组件的配置状态直接决定你后面的成败。很多老手觉得这些是常识，顺手就过了，反而把新手卡死在起跑线。

1.3 你的系统可能需要的额外认知（Windows 用户重点看）

如果你用的是 macOS 或 Linux，环境相对清爽；如果是 Windows，大概率会碰上 PowerShell 脚本策略、系统编码格式、终端重启这些破事。

提前打个预防针：下面出现任何看似多余的“重启终端窗口”“执行策略修改”，都不是浪费时间，而是在给后面排除隐患。我在文章后面会用一整章讲那些必然翻车的报错，你现在花两分钟处理，比到时候研究两小时划算得多。

2. 被 90% 的人跳过的那 2 分钟：装完 Node.js 先做三项自检

2.1 自检一：Node.js 装完不等于“能用”，先验证这个命令

Claude Code 官方推荐通过 npm 安装，npm 是 Node.js 自带的包管理器。所以第一步永远是装 Node.js，这没有争议。

但争议点在这里：很多人在安装 Node.js 时一路点“Next”，装完直接打开浏览器、下载 VS Code、开始复制安装 Claude Code 的命令，完全没有确认 Node.js 是否真的进入了系统的可执行路径。

结果就是终端里敲 npm install -g @anthropic-ai/claude-code，系统回你一句：

无法将“npm”识别为 cmdlet、函数、脚本文件或可运行程序的名称。

这句话的原意是：系统在所有能找程序的地方都翻了，没找到叫 npm 的程序。但你明明刚装过 Node.js，为什么找不到？

最常见的两种原因：安装过程没有把 Node.js 写入环境变量，或者安装完成后你没有重开终端窗口。

第二种情况极其常见。Windows 下安装 Node.js 时确实会写环境变量，但已经打开的终端窗口不会自动刷新环境变量。你在安装 Node.js 之前就开着的那个 PowerShell 窗口，里面保存的还是旧的环境变量快照。安装完 Node.js 后如果不关掉重开，系统就不知道 npm 已经存在了。

所以自检第一项就是：重开一个全新的终端窗口，然后执行：

bash复制node -v
npm -v

看到类似 v20.11.0 和 10.2.4 的输出，才算通过。如果 node -v 能显示版本但 npm -v 报错，说明 Node 装得不干净，建议直接去官网下载 LTS 版本重装，别在 npm 上单点排查浪费时间。

2.2 自检二：PowerShell 执行策略，Windows 用户最容易忽略的隐形门槛

Node.js 验证通过后，先别急着复制安装命令。Windows 用户还差一个非常关键的检查。

npm 全局安装的包在 Windows 上通常会生成一个 .ps1 文件，也就是 PowerShell 脚本。Windows 的 PowerShell 为了安全默认禁止执行任何脚本（执行策略为 Restricted），如果你跳过这一步，安装时可能看到权限错误，或者更常见的场景是：安装命令执行成功了，但敲 claude 的时候系统弹出一句“无法加载文件 ... 因为在此系统上禁止运行脚本”。

解决办法很简单，在当前用户范围内修改执行策略为 RemoteSigned。意思是：本地创建的脚本可以运行，从网上下载的脚本必须有可信签名。

powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

终端会问你是否确认更改，输入 Y 回车即可。验证是否生效：

powershell复制Get-ExecutionPolicy -List

看当前用户这行是否为 RemoteSigned。

为什么不建议用 Unrestricted（完全放开）？说实话，对于绝大多数个人开发机，Unrestricted 也不会立刻出什么大问题，但这是一个“最小必要权限”的习惯问题。你只是要让本地安装的 npm 工具能跑起来，没必要给所有下载脚本放行。养成好习惯，后面少吃亏。

2.3 自检三：确认终端会话环境“干净且清爽”

第三项自检很多人会忽略，但它能避免后续大量杂音干扰判断。

1. 使用 Windows Terminal 而不是老版控制台。Win11 自带，Win10 可以在微软商店免费安装。它能统一处理 UTF-8 编码，减少中文乱码概率。
2. 检查当前目录不是系统目录。不要在你的用户根目录或 C 盘系统目录下直接运行 Claude Code，建议先新建一个项目文件夹，比如 D:\projects\test-claude，然后在这个文件夹里打开终端。
3. 验证 npm 源能正常访问。执行：

   bash复制npm config get registry
   

   如果返回的是 https://registry.npmjs.org/ 或某个可访问的镜像地址，说明包下载渠道正常。如果你在企业内网，可能需要在 npm 源配置上额外折腾，但那是另一篇文章的范畴了。

这三项自检加起来不会超过 2 分钟，但它们解决的是 90% 新手最初的三个报错来源：命令找不到、脚本被禁止执行、环境错乱导致安装了却无法定位。

3. 安装命令与首次启动：把报错消灭在 claude --version 之前

环境自检通过后，真正安装只需要一条命令：

bash复制npm install -g @anthropic-ai/claude-code

-g 表示全局安装，这样你在电脑任何位置打开终端都能使用 claude 命令。等待进度条走完，你会看到类似下面的输出：

bash复制added XXX packages in XXs

如果这一步卡了很久或者说网络超时，大概率是 npm 源访问不畅。可以临时切换镜像源：

bash复制npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

这只是把下载源换成国内镜像，命令本身没有变化。安装成功后不要立刻急着启动对话，先做最小化验证：

bash复制claude --version

看到版本号输出就说明安装链路通了。如果你之前开了 Claude Code 相关扩展、VS Code 或其他占用终端的程序，先全部关掉重开再执行验证。

对于 macOS 和 Linux 用户，其实还有另一种官方安装方式，一条 curl 脚本自动搞定。但我个人仍然推荐 npm 方式，原因有三个：安装位置统一管理，升级方便（npm update -g @anthropic-ai/claude-code），卸载干净（npm uninstall -g @anthropic-ai/claude-code）。用 curl 脚本装的话，卸载时需要手动找文件，对零基础用户不够友好。

首次运行时，事情开始变得有趣。如果你有 Claude 的订阅账号，在项目目录下直接运行 claude，它会提示登录并给出一段授权链接，浏览器里确认授权即可。

但这里有个高频翻车点，尤其是国内用户想通过某些中转服务或企业内网代理访问，或者企业账号、中转账号本身没有开放 Claude Code 权限时，会看到一行冷冰冰的报错：

your organization has disabled claude subscription access for Claude Code

先看官方订阅用户的处理思路：你的订阅层级或组织策略没有开放 Claude Code 功能，或者管理员在控制台里禁用了 CLI 访问。这个只能在账号层面解决，和安装无关。用个人订阅账号一般不存在这个问题；如果你用的是公司账号，需要找管理员开通对应权限。

如果你没有 Claude 订阅，也不打算折腾海外支付那一摊子事，可以跳到第 5 章，用第三方模型把 Claude Code 跑起来。不想跳的话也行，先把 VS Code 集成那章看完，很多基础配置逻辑是通用的。

4. VS Code + Claude Code 的新手配置：装好之后别急着乱试

4.1 在 VS Code 里调出 Claude Code 的两种路径

主流做法有两种：

1. 直接在 VS Code 的终端里运行 claude。按 Ctrl + ` 调出终端面板，确认当前路径在你想要的项目目录，然后敲 claude。这是最简单、最不容易出错的方式，终端渲染、编码、颜色都顺带适配好了。
2. 安装官方 Claude Code 扩展。在 VS Code 扩展商店搜索 Claude Code，安装后在侧边栏会出现专用面板。扩展的好处是可视化程度高，能看到对话历史、文件变更等，还能直接在代码里右键让 Claude 处理选中区块。

新手我建议从第一种开始——先让整个工具链在终端里跑通，再上图形面板。因为一旦出问题，你能区分是 CLI 问题还是扩展桥接问题。直接上扩展，报错时你根本不知道错误来自哪一层。

4.2 第一次会话前，必须知道的三个基本操作

第一次进入 Claude Code 的交互界面，你可能会有点懵：没有按钮，只有一个等待输入的光标，和一个不断变化的提示符。

这里说三个新手最常用的操作：

• /clear：清空当前对话上下文，重新开始。注意它不是退出程序，只是把聊天记录清了，让模型忘掉之前聊过什么。
• /exit：退出 Claude Code。长时间不用时没必要一直挂着。
• /cost：查看本次会话消耗的 token 费用。用 API 模式跑的话，这个命令你迟早会爱上。

另外还有一个极其重要的概念：Claude Code 有自主执行能力。它会根据你的指令自动读文件、写文件、跑命令。这让它强大，也让新手恐惧——“它会不会乱改我的代码？”

实际上它默认会在执行有风险操作前征求你的确认，但它一次能连续改动多个文件，建议你第一次试玩时找一个不重要的测试项目，不要直接在重要项目里体验，免得让它一通操作猛如虎，改完你也不知道改了什么。

4.3 顺手解决几个新手高频的小毛病

这几个问题几乎是群里的日经话题，直接在这里一次说清。

中文乱码：Windows 终端默认可能不是 UTF-8 编码，中文输出变成一堆方块或问号。在终端里执行：

powershell复制chcp 65001

切换到 UTF-8 代码页。如果一次会话后失效，可以在 PowerShell 配置文件里固定设置。

怎么让它一直用中文回答：进入 Claude Code 后输入 /config，在配置选单里看一下是否有语言设置项；不同版本入口文案不同，原理都是一样的——把“始终用中文回答”写进项目记忆文件（CLAUDE.md）。更稳定的方式是直接编辑项目根目录下的 CLAUDE.md，没有就新建，写入一行：

code复制Always respond in Chinese.

这个文件会被 Claude Code 在每个会话开始时自动读取，相当于一份常驻指令。

怎么保存对话历史：Claude Code 默认会在本地记录会话数据，位置在用户目录的 ~/.claude/projects/ 下，按项目路径哈希分目录存放。里面是 JSONL 格式的记录文件，可以直接翻，也可以用来做数据分析。如果你需要导出成可读文档，官方没有一键导出，但可以在会话里逐段复制，或者写个小脚本解析 JSONL。零基础用户不需要太深入，知道历史在本地不会丢失就够了。

关闭提示音：如果你觉得每次输出完成都响一声很烦，去 /help 看看当前版本支持的声音或通知设置项，不同版本的命令和入口不完全一样，但一定能在帮助里找到对应关键字，通常和 sound、audio、notification 有关。老版本的 --no-sound 参数在部分新版本中已弃用，所以我更推荐你直接查看/help，不要死记硬背网上搜来的老命令。

5. 不折腾 Claude 订阅也能跑：把 Claude Code 接到 DeepSeek 等第三方模型

5.1 先说清楚原理：为什么 Claude Code 能接第三方模型

很多零基础用户误以为 Claude Code 只能配 Claude 官方 API，其实 Claude Code 的架构里，模型访问部分是可以替换的。

Claude Code 官方支持通过环境变量指定 API 地址和密钥。这就意味着，任何兼容 Anthropic API 格式的服务都可以接入。而社区很快发现了一个更实用的玩法：把 OpenAI 兼容接口转换成 Anthropic 格式，这样 Claude Code 就能当一个通用 AI 编程助手壳，底层接入 DeepSeek、通义千问、Kimi、Ollama 本地模型等不同的模型服务。

DeepSeek 等模型的 API 价格远低于 Claude 官方 API，而且关键是获取容易、支付方便。所以“Claude Code 壳 + DeepSeek 模型”成为很多人的日常配置，这也是为什么网上相关搜索热度那么高。

5.2 实操：用环境变量的方式接 DeepSeek（最简单）

先说明一点：如果你只是要快速验证，不想再折腾第三方管理工具，可以直接使用环境变量。但 Claude Code 原生认的是 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 这类变量，直接把变量指到 DeepSeek 官方接口在大多数情况下是不行的，因为 DeepSeek 接口是 OpenAI 风格，和 Anthropic 风格不兼容。所以网上很多人安装了一个中间层转换工具，或者用 CC Switch、claude-code-router 这类社区工具做协议转换。

这里我给新手推荐一条已经验证过的路线：安装一个叫 CC Switch 的配置切换工具，它本质上是一个 GUI 或 TUI 程序，用来管理 Claude Code 的供应商配置。网上很容易搜到安装命令，装完后它会提供不同的供应商模板，选择 DeepSeek 并填入自己的 API Key，它会自动处理好协议转换和模型 ID 映射。

切到 DeepSeek 后首次启动，如果之前用过官方配置，可能需要清掉旧的环境变量。Windows PowerShell 下：

powershell复制Remove-Item Env:ANTHROPIC_BASE_URL
Remove-Item Env:ANTHROPIC_AUTH_TOKEN

然后重启 claude。

启动后随便问一句“你是谁，什么模型”，看它怎么回答就知道切换是否成功。如果它能答上来，说明链路已经通了。

5.3 “is not a model” 报错的真相：模型 ID 写错了

网上搜索 Claude Code 接入 DeepSeek 的报错时，你会看到类似这样的热词：

deepseek-v4-flash is not a model this version of claude code recognizes

这句话的意思是：Claude Code 收到你指定的一个模型名称，但它不认识。原因几乎只有一个——模型 ID 填错了。

DeepSeek 真实可用的模型 ID 是 deepseek-chat 和 deepseek-reasoner，不是什么 v4-flash、v4-pro。网上那些以 v4 开头命名的模型，很可能是某些第三方网关为了营销造出来的名字，并不等于你实际能调用的模型。

如果你在配置文件里填的模型 ID 是该服务文档里根本不存在的，自然会被 Claude Code 拒绝。遇到这类报错时，去你的模型服务商后台文档里查真实模型 ID，别在报错文案里找答案。

5.4 进阶玩法：Ollama 本地模型跑 Claude Code

Ollama 这类本地模型管理器也能和 Claude Code 配合。好处是模型跑在本地，无 API 费用，私密性强，断网也能用。坏处是对硬件要求高，响应速度慢，代码能力跟 DeepSeek 这类大规模商用模型有差距。

新手如果只是好奇体验，可以在 Ollama 装一个 7B 或 14B 参数的模型玩一玩；如果真想拿 Claude Code 做正经项目开发，本地小模型目前的体验并不理想。这条路线更适合之后想折腾本地 AI 的老手。

6. 安装阶段高频报错对照清单：遇到直接抄作业

下面的内容不是原理讲解，而是一份“报错现象 → 原因 → 解决方案”的对照清单。我不是让你背，而是希望你在遇到某个报错时能快速定位。

6.1 “failed to run claude code: error: could not locate the claude cli on path”

如果你在 VS Code 的 Claude Code 扩展里看到这段，原因是扩展进程找不到 claude 命令。

常见场景：你安装 Claude Code 用的是 PowerShell，但 VS Code 是安装前就启动的，扩展继承的环境变量里没有新增的 npm 目录。解决方法很简单：完全关闭 VS Code，重新打开。如果还不行，手动把 npm 全局目录加入系统环境变量 PATH。Windows 下通常路径是 C:\Users\你的用户名\AppData\Roaming\npm。

6.2 “your organization has disabled claude subscription access for claude code”

这个报错上一章提过，这里再强化一下。它和你电脑配置无关，属于“凭证没有权限使用 Claude Code”的范畴。

两种情况：一是你登录的是组织订阅账号，管理员没给 Claude Code 权限；二是你用第三方订阅服务但服务商后端限制 Claude Code 路由。第一种联系账号管理员，第二种换一个支持 Claude Code 的模型供应商或方案。无论如何，这都不是重装能解决的。

6.3 PowerShell 安装报错：“无法加载文件，因为在此系统上禁止运行脚本”

如果你跳过了第 2 章的自检，大概率会在这里翻车。执行：

powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这是当前用户级修改，不会影响系统其他用户。改完重开终端即可。

6.4 “claude 不是内部或外部命令”

这不是报错，这是说明系统根本没找到命令。依次排查：

1. 安装时是否真的看到成功输出？
2. 终端窗口是不是安装之前开的？重开一个。
3. 全局 npm 目录是否在 PATH 里？

把三件事全部做一遍，90% 能解决。

6.5 安装时卡住或者超时

npm 官方源在国内访问不稳定，可以临时切换镜像源安装，或者直接配置持久化的 npm 镜像：

bash复制npm config set registry https://registry.npmmirror.com

装完工具之后可以不改回去，影响不大。

6.6 中文显示乱码

终端执行：

powershell复制chcp 65001

如果持久化需求，在 Windows Terminal 的设置里把默认编码改为 UTF-8。

6.7 模型报错 “is not a model this version of claude code recognizes”

见 5.3 节，去模型服务商文档里查真实模型 ID。如果你用了 CC Switch，确认它在切换时填的是目标服务真正支持的模型名称，有些配置模板里写的名字未必是实时更新的。

7. 最后再分享一点实际经验

这些年带着不少同事和朋友从零开始折腾命令行 AI 工具，最深的体会是：装 Claude Code 从来不是什么高深技术活，真正卡住新手的全是环境问题。很多人一遇到报错就怀疑工具不行、电脑不行、自己不行，其实 Agent 类工具的门槛本来就在环境配置上，耐心对照步骤一步步排查，基本都能解决。

另外想多说一句：第一次成功跑通后，别急着让 Claude Code 去改复杂的项目代码。先用它做点小任务，比如“帮我写一个 Python 脚本批量重命名文件”“解释一下这个目录的结构”，感受一下它的工作方式、确认机制和 token 消耗节奏。等你对它的“脾气”摸熟了，再逐渐放权去做大改动的任务。

后面你还可以继续扩展的方向包括：把 CLAUDE.md 打磨成你自己的专属指令库，让它在不同项目里保持一致的代码风格；学习用 /compact 压缩上下文来节省 token；折腾 CC Switch 或者 Ollama 本地模型；甚至把它接入 CI 流程做自动代码审查。

路是一步步走出来的。只要你把第 2 章那 2 分钟的环境自检认真做完，后面基本上就是一马平川。