Claude Code 是 Anthropic 给开发者提供的终端编程助手和网页聊天最大的区别是你可以在项目目录里直接启动它让它读文件、改代码、跑命令、生成文档。很多人第一次接触时会纠结几个问题安装用 npm 还是桌面端VSCode 里怎么用能不能接第三方模型“Skills”到底怎么装其实把这些拆开看核心链路就一条装好 CLI配好 API Key在项目目录里跑通一次对话。这篇不绕概念直接按这条链路走重点覆盖安装、首次运行、写文档、模型配置、Skills 和常见报错。适合刚接触 Claude Code、想从零开始稳定使用的开发者也适合已经装过但遇到过各种莫名其妙报错的人。我先说结论如果你不想折腾优先装命令行版CLI先在一个小目录里让它生成一个文件再考虑 VSCode 扩展、桌面端和第三方模型。大多数“用不起来”的情况都发生在前置环境没确认好或者装的东西太多、不知道报错属于哪一层。1. 先搞清楚 Claude Code 是什么再决定先装哪一形态Claude Code 不是普通聊天助手。你在网页里跟模型聊天它给你一段代码你自己复制到文件里Claude Code 做的事情更接近“一个能使用终端的智能体”它知道你当前在哪个目录能读取文件内容能创建文件也能在授权后执行命令。这个特点决定了它适合写文档、改代码、批量整理文件、生成项目说明这类需要落到实际文件系统的任务。1.1 核心能力不是聊天而是“能操作你的项目目录”真正值得关注的不是它能聊多好而是它能不能在项目目录里完成一连串操作。比如让它给一个项目写 README它会先去读目录结构再看关键文件然后才动手。所以判断它是否正常工作不能只看最后输出了什么还要看它在执行过程中是否在读取文件、是否请求写权限、日志里有没有报错。这个能力也带来边界它不能替你做所有事。上下文窗口有限工具权限需要确认环境变量、路径、依赖版本都会影响结果。低配置机器能跑不代表适合批量跑很重的任务支持多文件也不代表所有格式都稳定。1.2 CLI、VSCode 扩展、桌面端最容易选错的三个入口很多人一开始就分不清三个入口CLI核心形态。安装后在任何终端里输入claude就能进入交互模式。VSCode 扩展在编辑器里使用提供更贴近代码的入口但多数情况下仍然依赖 CLI 已经安装。桌面端这个词最容易混淆。很多搜索到的“Claude 桌面应用”是 Claude 的聊天桌面端不是 Claude Code 的桌面封装。如果你看到需要下载一个带界面的 Claude Code 桌面版先确认它来自官方还是第三方封装。我的建议是不要一上来就在桌面端上纠结。Claude Code 的官方主推形态是 CLI版本迭代、文档和功能支持都围绕它展开VSCode 里使用也建议先装好 CLI再在集成终端里调用。桌面端如果想要一个按钮点击的启动器等 CLI 跑通了再体验也不迟。1.3 我建议的起步选择不同人群的起步方式不一样纯新手、只想先试装 CLI用系统默认终端跑通一次对话。开发者在 VSCode 写代码装 CLI直接在 VSCode 集成终端里启动不一定要额外装扩展。想尝试 Skills 和第三方模型仍然先装 CLI把交互模式用熟再碰进阶配置。一句话先让“命令行里的 Claude Code”正常工作再去扩展它。装得越多报错层越多。CLI 报错基本就是环境变量、Node、权限、上游服务这几个原因加上扩展和桌面端后还要多查一层扩展版本、启动器配置。注意不要一上来就装 CLI、扩展、桌面端三套先让命令行版本跑通再决定要加哪一层。2. 安装前的环境确认和最小可运行验证2.1 先检查 Node.js 和终端环境Claude Code 通过 npm 全局安装所以 Node.js 是第一道前提。先打开终端确认两个命令能输出版本号node -v npm -v如果提示command not found先去安装 Node.js建议选择最新的 LTS 版本。安装完成后重新打开终端再执行上面的命令。Windows 用户建议用 PowerShell 或 Windows TerminalmacOS 和 Linux 用户注意 npm 全局 bin 目录要出现在 PATH 里。这一步很基础但很多人卡在这里npm 装完了claude命令找不到本质是 PATH 没生效。2.2 安装命令和安装后的自检安装命令一般是这样npm install -g anthropic-ai/claude-code安装完成后不要急着进入对话先做两个自检claude --version claude --help能输出版本号说明命令已经可用能看到帮助信息说明至少没有在启动阶段崩溃。如果命令在安装后找不到通常不是 Claude Code 本身的问题而是 npm 全局目录不在 PATH 里。可以先执行npm config get prefix把输出的全局 bin 目录加入 PATH或者用 nvm 这类版本管理工具安装 Node减少权限目录问题。2.3 配置 API Key环境变量优先别写死在代码里要让 Claude Code 能真正调用模型需要配置 API Key。最直接的方式是通过环境变量macOS / Linuxexport ANTHROPIC_API_KEY你的密钥Windows PowerShell$env:ANTHROPIC_API_KEY你的密钥执行后重新打开终端或者在当前终端继续使用。也可以在项目里用 .env 文件配合加载工具但要注意不要把密钥提交到 git不要写死在脚本和文档里。判断环境变量是否生效可以执行echo $ANTHROPIC_API_KEY注意环境变量只对当前终端会话有效。换一个终端窗口变量可能就没了于是报 401 或认证失败。2.4 第一次对话让它生成一个小文件环境确认完毕后进入一个空目录或小项目目录运行claude进入交互界面后先不要 Claude Code 入门指南：安装、配置与 Skills 实战
Claude Code 是 Anthropic 给开发者提供的终端编程助手和网页聊天最大的区别是你可以在项目目录里直接启动它让它读文件、改代码、跑命令、生成文档。很多人第一次接触时会纠结几个问题安装用 npm 还是桌面端VSCode 里怎么用能不能接第三方模型“Skills”到底怎么装其实把这些拆开看核心链路就一条装好 CLI配好 API Key在项目目录里跑通一次对话。这篇不绕概念直接按这条链路走重点覆盖安装、首次运行、写文档、模型配置、Skills 和常见报错。适合刚接触 Claude Code、想从零开始稳定使用的开发者也适合已经装过但遇到过各种莫名其妙报错的人。我先说结论如果你不想折腾优先装命令行版CLI先在一个小目录里让它生成一个文件再考虑 VSCode 扩展、桌面端和第三方模型。大多数“用不起来”的情况都发生在前置环境没确认好或者装的东西太多、不知道报错属于哪一层。1. 先搞清楚 Claude Code 是什么再决定先装哪一形态Claude Code 不是普通聊天助手。你在网页里跟模型聊天它给你一段代码你自己复制到文件里Claude Code 做的事情更接近“一个能使用终端的智能体”它知道你当前在哪个目录能读取文件内容能创建文件也能在授权后执行命令。这个特点决定了它适合写文档、改代码、批量整理文件、生成项目说明这类需要落到实际文件系统的任务。1.1 核心能力不是聊天而是“能操作你的项目目录”真正值得关注的不是它能聊多好而是它能不能在项目目录里完成一连串操作。比如让它给一个项目写 README它会先去读目录结构再看关键文件然后才动手。所以判断它是否正常工作不能只看最后输出了什么还要看它在执行过程中是否在读取文件、是否请求写权限、日志里有没有报错。这个能力也带来边界它不能替你做所有事。上下文窗口有限工具权限需要确认环境变量、路径、依赖版本都会影响结果。低配置机器能跑不代表适合批量跑很重的任务支持多文件也不代表所有格式都稳定。1.2 CLI、VSCode 扩展、桌面端最容易选错的三个入口很多人一开始就分不清三个入口CLI核心形态。安装后在任何终端里输入claude就能进入交互模式。VSCode 扩展在编辑器里使用提供更贴近代码的入口但多数情况下仍然依赖 CLI 已经安装。桌面端这个词最容易混淆。很多搜索到的“Claude 桌面应用”是 Claude 的聊天桌面端不是 Claude Code 的桌面封装。如果你看到需要下载一个带界面的 Claude Code 桌面版先确认它来自官方还是第三方封装。我的建议是不要一上来就在桌面端上纠结。Claude Code 的官方主推形态是 CLI版本迭代、文档和功能支持都围绕它展开VSCode 里使用也建议先装好 CLI再在集成终端里调用。桌面端如果想要一个按钮点击的启动器等 CLI 跑通了再体验也不迟。1.3 我建议的起步选择不同人群的起步方式不一样纯新手、只想先试装 CLI用系统默认终端跑通一次对话。开发者在 VSCode 写代码装 CLI直接在 VSCode 集成终端里启动不一定要额外装扩展。想尝试 Skills 和第三方模型仍然先装 CLI把交互模式用熟再碰进阶配置。一句话先让“命令行里的 Claude Code”正常工作再去扩展它。装得越多报错层越多。CLI 报错基本就是环境变量、Node、权限、上游服务这几个原因加上扩展和桌面端后还要多查一层扩展版本、启动器配置。注意不要一上来就装 CLI、扩展、桌面端三套先让命令行版本跑通再决定要加哪一层。2. 安装前的环境确认和最小可运行验证2.1 先检查 Node.js 和终端环境Claude Code 通过 npm 全局安装所以 Node.js 是第一道前提。先打开终端确认两个命令能输出版本号node -v npm -v如果提示command not found先去安装 Node.js建议选择最新的 LTS 版本。安装完成后重新打开终端再执行上面的命令。Windows 用户建议用 PowerShell 或 Windows TerminalmacOS 和 Linux 用户注意 npm 全局 bin 目录要出现在 PATH 里。这一步很基础但很多人卡在这里npm 装完了claude命令找不到本质是 PATH 没生效。2.2 安装命令和安装后的自检安装命令一般是这样npm install -g anthropic-ai/claude-code安装完成后不要急着进入对话先做两个自检claude --version claude --help能输出版本号说明命令已经可用能看到帮助信息说明至少没有在启动阶段崩溃。如果命令在安装后找不到通常不是 Claude Code 本身的问题而是 npm 全局目录不在 PATH 里。可以先执行npm config get prefix把输出的全局 bin 目录加入 PATH或者用 nvm 这类版本管理工具安装 Node减少权限目录问题。2.3 配置 API Key环境变量优先别写死在代码里要让 Claude Code 能真正调用模型需要配置 API Key。最直接的方式是通过环境变量macOS / Linuxexport ANTHROPIC_API_KEY你的密钥Windows PowerShell$env:ANTHROPIC_API_KEY你的密钥执行后重新打开终端或者在当前终端继续使用。也可以在项目里用 .env 文件配合加载工具但要注意不要把密钥提交到 git不要写死在脚本和文档里。判断环境变量是否生效可以执行echo $ANTHROPIC_API_KEY注意环境变量只对当前终端会话有效。换一个终端窗口变量可能就没了于是报 401 或认证失败。2.4 第一次对话让它生成一个小文件环境确认完毕后进入一个空目录或小项目目录运行claude进入交互界面后先不要