之前第一次折腾 Claude Code 时我其实是有点懵的npm 装完发现claude命令找不到登录完又提示组织账号没权限项目文件倒是能读但稍微复杂一点的生成逻辑总是靠现写提示词硬撑。后来把安装、认证、配置、会话管理和 Skills 扩展逐个捋顺之后才真正把它当成了主力生产力工具。这篇文章想按“从 0 到 1”的顺序把 Claude Code 的安装方式、登录认证、配置体系、常用命令、进阶玩法、常见报错排查和工程实践完整讲一遍。不管你是刚接触 AI 编程助手的新手还是已经在用其他 AI 工具、想评估对比的开发者都可以直接照着操作。1. Claude Code 是什么为什么值得学1.1 一句话理解Claude Code 是 Anthropic 推出的 AI 编程代理工具它不是一个网页聊天框而是跑在你的终端、IDE 和桌面应用里的一个“编码 Agent”。简单说你可以在命令行里直接对它下达任务阅读项目代码修改某个文件写单元测试提交 Git分析报错生成技术文档。它会根据当前项目的文件内容、命令输出和你的指令自主地调用工具、读取代码上下文并完成多步操作。也就是说它不只是“帮你补全代码片段”而是“帮你在项目里干活”。1.2 它能解决什么问题传统 AI 对话工具最大的问题是“上下文脱离项目”。你复制一段代码进去它只能泛泛地分析但它看不到整个项目的目录结构、依赖关系、最近改动。Claude Code 解决的是这类问题修改一个功能时能自动关联相关文件和调用链阅读大型项目时不用手动把十几个文件一个个贴进对话执行测试或命令后能读取输出结果并根据报错继续调整需要重复执行的项目规范、代码风格、提交格式可以通过项目配置固化下来。所以它更适合用在真实项目开发、代码重构、技术文档维护、复杂问题定位等场景而不是简单的“写个 Python 爬虫”“生成一段排序代码”。1.3 CLI、桌面版和 VS Code 插件的关系Claude Code 目前有几种常见形态很多人容易搞混。CLI 命令行工具核心形态。在终端中执行claude命令启动几乎全平台可用也是后续 VS Code 插件和桌面版依赖的基础。VS Code 插件适合习惯在编辑器里工作的开发者。安装插件后可以在编辑器中唤起 Claude Code 面板选区代码直接提问查看 diff 等。桌面版Claude Desktop一种带图形界面的运行环境适合不想频繁操作终端、又想用 Claude Code 管理项目的人。在开始之前建议先理解无论哪种形态底层使命是一致的都是“让 AI 进入你的工程项目”。如果你只是日常开发终端 CLI 加 VS Code 插件基本就够用了。2. 环境准备与安装方式2.1 安装前的环境要求Claude Code 的版本迭代比较快所以下面这些版本只是“基础要求”具体请以官方最新说明为准操作系统Windows、macOS、Linux 均可但不同平台在终端命令上略有差异。Node.js官方主要推荐通过 npm 安装所以需要先装 Node.js建议使用 LTS 版本。包管理器npm 会随 Node.js 一起安装也可以使用 pnpm、yarn 等替代。终端Windows 建议使用 PowerShell 7 或 Windows TerminalmacOS 使用自带 Terminal 或 iTerm2 均可。如果你的机器上还没有 Node.js建议先到 Node.js 官网安装 LTS 版本。安装完成后在终端里执行node -v npm -v能正常输出版本号就说明 Node.js 环境没有问题。2.2 使用 npm 安装 CLICLI 是 Claude Code 的核心。安装命令很简单npm install -g anthropic-ai/claude-code执行之后npm 会下载并全局安装 Claude Code。安装完成后验证是否成功claude --version如果此时提示找不到命令常见原因有两个npm 全局安装目录没有加入系统 PATH安装过程因为网络或权限问题中断。Windows 下可以检查 npm 全局目录npm config get prefix确认该目录是否在你系统的环境变量PATH中。如果还不确定可以重新执行一次安装并留意终端里的安装日志。2.3 安装 VS Code 插件如果你习惯在 VS Code 中开发推荐再安装官方插件。安装步骤打开 VS Code点击左侧扩展图标搜索关键词Claude Code找到对应插件点击 Install重启或重新加载窗口。安装完成后VS Code 左侧或命令面板中会出现 Claude Code 相关入口。通过插件你可以把选中的代码发送给 Claude Code也可以直接让它分析当前打开的文件、生成测试、修复 lint 错误等。注意VS Code 插件通常会调用本机的claude命令行工具。也就是说即使装了插件也建议先完成 CLI 的安装。2.4 桌面版与内置终端除了 CLI 和 VS Code 插件Claude Code 桌面版也在逐步流行。桌面版本质上仍会依赖本地的 Claude Code 运行环境只是外面包了一层图形界面适合用来管理多个项目、查看任务历史。如果你在桌面版中遇到类似claude app host claude code binary not available的提示大概率是本地没有完整安装 CLI或者桌面版没有找到 CLI 的下载路径。此时优先回到命令行把 CLI 装好再重启桌面版。2.5 验证安装安装完成后可以运行一个最简单的命令确认 Claude Code 能正常响应claude 你好请介绍一下你自己如果启动了交互界面并等待继续输入说明基本可用如果提示需要登录请看下一节认证内容。3. 登录认证与配置体系3.1 登录认证方式Claude Code 首次使用时需要完成账号认证。运行claude终端通常会显示一个授权链接通过浏览器登录账号并授权后终端会自动完成认证。这种方式属于 OAuth 登录适合个人账号日常使用。如果你使用的是企业或组织账号登录时可能遇到类似提示your organization has disabled claude subscription access for claude code意思是当前组织没有开放 Claude Code 权限。这种情况不是本机配置问题需要找组织管理员在后台开启相关权限。3.2 使用 API Key 配置很多开发者会在团队或自动化场景中使用 API Key 而不是 OAuth 登录。这时可以通过环境变量或配置文件指定。终端临时指定export ANTHROPIC_API_KEY你的 API Key claude如果把 API Key 写到配置文件里可以避免每次启动都设置环境变量。Claude Code 的配置文件位于~/.claude/settings.json里面可配置环境变量、默认模型、权限等。示例{ env: { ANTHROPIC_API_KEY: 你的 API Key } }配置完成后重启 Claude Code 即会生效。需要注意不要把包含真实 API Key 的文件提交到 Git 仓库。3.3 项目级指令文件 CLAUDE.mdCLAUDE.md是 Claude Code 最值得学习的配置之一。它相当于项目的“给 AI 看的说明文档”。当 Claude Code 进入一个项目时它会自动读取根目录下的CLAUDE.md把它当作最重要的项目上下文。也就是说你不需要每次对话都重复“我们这个项目是 Java 项目”“接口要返回统一结构”把这些规则写进CLAUDE.md就行。示例CLAUDE.md# 项目说明 这是一个 Spring Boot 3 项目使用 Maven 构建Java 版本为 17。 # 常用命令 - 构建mvn clean package - 测试mvn test - 启动mvn spring-boot:run # 代码规范 - 所有 Controller 返回值使用 Result 包装类 - 数据库操作必须通过 Mapper 层禁止在 Service 中直接写 JDBC - 日志使用 slf4j禁止使用 System.out有了这份文件后Claude Code 在生成代码、修改代码时会主动遵循这些规则。除了项目根目录你也可以在用户全局目录~/.claude/CLAUDE.md中写一些跨项目的个人偏好比如“默认回答使用中文”“不要生成多余注释”等。3.4 Settings 文件详解Claude Code 支持多级配置理解文件层级对团队协作非常重要。~/.claude/settings.json用户级全局配置对所有项目生效。.claude/settings.json项目级共享配置建议提交到 Git 仓库团队统一使用。.claude/settings.local.json项目级个人配置一般加入.gitignore不提交。常见配置项包括model默认使用的模型env环境变量比如 API Key、Base URLpermissions权限规则控制 Claude Code 可以执行哪些命令、读写哪些文件hooks钩子脚本在执行特定动作前后触发自定义逻辑includeCoAuthoredByGit 提交时是否附上 AI 协作署名等。示例.claude/settings.json{ model: claude-sonnet-4-5, permissions: { allow: [ Bash(npm run lint), Read(.) ], deny: [ Bash(rm -rf *) ] } }注意权限字段的具体写法和可用值会随版本变化建议以当前版本的帮助文档为准。关键是理解“允许什么、拒绝什么”的配置思想。3.5 目录结构总结用一段时间后你可能会在项目里看到这些文件和目录my-project/ ├── .claude/ │ ├── settings.json │ ├── settings.local.json │ └── skills/ ├── CLAUDE.md └── ...用户本机还会看到~/.claude/ ├── CLAUDE.md ├── settings.json ├── skills/ └── ...弄清楚这些目录的作用后面配置 Skills、切换模型时就不会迷路。4. 核心使用方式从命令行到多模式实战4.1 启动交互模式安装并认证完成后最直接的使用方式是在项目目录下运行claude进入交互模式后你可以像聊天一样输入指令。比如请帮我看看当前项目的目录结构并解释每个模块的作用。Claude Code 会读取文件并回答。如果你想让它修改代码要尽量给出清晰的边界例如把 utils/date.js 里的 formatTime 函数重构一下要求支持时区参数保留原有导出名并补上单元测试。在交互模式中还可以使用/help查看所有可用斜杠命令使用/model查看和切换模型。4.2 非交互命令模式如果不需要进入交互界面只想一次性提交任务可以使用-p参数也就是 print / 非交互模式claude -p 分析当前项目的 package.json列出所有生产依赖非交互模式适合写脚本、接入 CI/CD 流程。比如claude -p 根据 CHANGELOG.md 的模板生成本周版本更新说明 --output-format text在自动化脚本中可以捕获输出后继续处理。4.3 会话恢复与继续Claude Code 的会话是可以保存的。如果你在一次长对话中关闭了终端之后可以继续。相关参数# 继续上一个会话 claude --continue # 恢复某个历史会话 claude --resume当你需要分阶段处理同一个任务时恢复会话能让 AI 继续保留之前的项目上下文不用从头解释。4.4 斜杠命令与常用操作交互模式下常用斜杠命令包括/help查看帮助/clear清空当前会话上下文/compact压缩上下文减少 token 占用/cost查看当前会话费用消耗/model切换模型/logout退出登录。我个人的习惯是当对话历史太长、AI 开始“忘事”时先执行/clear重新整理一次任务描述或者把关键结论写进项目文档再让 Claude Code 读取而不是一味延长对话。4.5 VS Code 插件实战VS Code 插件的常见操作流程打开项目选中最想提问的代码块右键选择 Claude Code 相关命令在输入框中描述需求例如“为选中函数补充 JSDoc 注释”插件会调用 Claude Code 生成修改建议并显示 diff确认后应用修改。这种方式比“复制代码到网页聊天框”高效得多因为插件能感知当前文件、选区、打开的其他文件上下文损失最小。5. 进阶玩法Skills、切换模型与文档生成5.1 Skills 技能包Skills 是 Claude Code 的一项扩展机制。你可以把它理解成给 AI 预装的“插件技能”。比如代码审查技能Git 提交信息生成技能数据库迁移脚本技能技术写作技能。Skills 一般以目录形式存在常见位置包括用户级~/.claude/skills/和项目级.claude/skills/。每个技能目录里通常包含一个描述文件例如SKILL.md用于说明该技能的用途、触发方式和参数。使用技能时Claude Code 会在合适的场景自动加载或通过/skills查看当前可用的技能列表。安装 Skills 的常见方式从 Git 仓库克隆技能包把技能目录复制到.claude/skills/重启 Claude Code 并验证。由于 Skills 社区发展很快不同技能包的安装要求差异较大建议优先使用有明确文档和示例的技能包。5.2 配置第三方模型服务Claude Code 原生主要面向 Anthropic 的模型服务。但不少团队会使用兼容 Anthropic API 格式的模型网关或者通过 OpenRouter 这类聚合服务接入其他模型。此时可以设置环境变量或配置文件{ env: { ANTHROPIC_BASE_URL: https://你的模型网关地址, ANTHROPIC_MODEL: 你使用的模型名, ANTHROPIC_API_KEY: 你的 API Key } }也有社区工具比如 cc-switch本质上就是帮助你快速管理和切换上面这几个配置项避免每次手工改settings.json。需要特别注意配置第三方模型服务时模型名必须是当前模型网关真实可用且能提供完整能力的模型名。如果写错可能遇到类似deepseek-v4-pro is not a model this version of claude code recognizes这个报错的含义是Claude Code 识别到了你配置的模型名但它不认可或当前环境不支持。排查时优先核对模型名是否正确网关地址是否正确当前 Claude Code 版本是否支持该模型网关是否兼容 Claude Code 依赖的 API 格式。5.3 用 Claude Code 写技术文档Claude Code 非常适合生成和维护技术文档。很多人在写文档时最痛苦的是“文档跟不上代码”而 Claude Code 可以直接读代码、读注释、读测试然后帮你生成文档初稿。例如在项目根目录执行claude -p 阅读 src 目录下的接口代码生成一份 API 文档包含接口路径、请求参数、返回结构输出到 docs/api.md它也能帮你维护 README根据当前项目的启动方式、环境变量、测试命令重新整理 README.md要求结构清晰。注意AI 生成的文档仍然需要人工核对尤其是涉及安全、权限、复杂业务逻辑的部分。文档生成后一定要让熟悉业务的同事 review。6. 常见问题与排查思路6.1 安装类问题问题现象常见原因解决思路claude 不是内部或外部命令npm 全局目录不在 PATH 中检查 npm 全局目录并加入 PATH安装缓慢或中断网络不稳定检查网络后重试或切换 npm 镜像源版本更新后功能异常旧版本缓存执行 claude --update 或重新安装6.2 认证与权限类问题问题现象常见原因解决思路登录后提示无订阅权限当前账号没有 Claude Code 访问权限检查账号订阅或联系管理员组织账号无法使用组织后台禁用了 Claude Code由管理员开启对应权限API Key 认证失败Key 失效或权限不足检查 Key 是否有效权限是否匹配6.3 模型配置类问题看到类似xxx is not a model this version of claude code recognizes报错按以下顺序排查执行claude --version确认当前版本执行/model或在配置文件中查看当前模型名确认模型名是否真实存在于你使用的模型服务中如果使用了第三方网关确认网关地址能正常访问、接口兼容 Anthropic 格式修改配置后重启 Claude Code。6.4 请求类错误问题现象常见原因解决思路429 / 529 错误请求过于频繁或服务繁忙稍后重试降低请求频率响应突然中断网络波动或超时检查网络并尝试恢复会话上下文过长单轮对话 token 超限使用 /compact 压缩或 /clear 重开遇到 529 时我最推荐的做法不是立刻换模型而是先停止并发任务等 1 到 2 分钟再重试避免反复触发限流。7. 最佳实践与工程建议7.1 项目指令先行不要让 Claude Code“猜”你的项目规则。在项目启动前先写好CLAUDE.md把技术栈、命令、代码规范、目录职责写清楚。这样可以显著提升 AI 生成代码的质量减少无效修改。7.2 最小权限原则Claude Code 能执行命令、读写文件但也意味着风险。生产环境、敏感目录、数据库操作都必须遵循最小权限原则不要让 Claude Code 默认拥有全部权限在permissions中显式允许、拒绝关键命令涉及删除、数据库变更、生产发布的命令先人工审查再手动或经授权执行。我的建议是高风险命令默认拒绝确需执行时再临时授权而不是一次性全部放行。7.3 会话与上下文管理AI 的上下文窗口是有限的。长会话会越来越慢也容易“遗忘”。合理做法每个任务独立会话不要把所有需求堆在一个会话里任务复杂时把需求、约束写进文档让 Claude Code 读取而不是反复追加提示词关键结论要沉淀到CLAUDE.md或项目文档中方便后续会话复用。7.4 安全边界Claude Code 生成的代码不一定天然安全。它写 SQL 时可能漏掉 WHERE 条件写命令时可能误操作文件。因此涉及数据库、鉴权、支付等敏感逻辑必须人工 review任何删除、批量更新、生产环境变更先备份、先测试不要把真实密钥写进项目文件或持久化到 Cloude Code 配置中。7.5 团队协作建议如果团队多人使用 Claude Code可以把以下文件纳入版本管理.claude/settings.json统一团队工具行为CLAUDE.md统一项目背景和代码规范docs/下的 AI 生成文档作为人工 review 后的沉淀产物。同时要把.claude/settings.local.json、.env、包含密钥的文件加入.gitignore避免隐私泄露。8. 总结与下一步规划这套从安装到实战的流程走下来你应该已经掌握了 Claude Code 的安装、登录、配置、交互模式、非交互模式、Skills、模型切换、文档生成和常见问题排查。核心要点可以总结为三句话先装好 CLI再配 VS Code 插件和桌面版用CLAUDE.md和settings.json把项目背景、权限边界固化下来把 Claude Code 当成“有上下文的编程助理”而不是一次性问答工具。接下来的学习路线建议先从自己的真实项目开始每天挑一个小任务交给它例如“补充单元测试”“重构一个函数”“生成接口文档”。等熟悉了它的行为边界再逐步尝试配置 Skills、接入团队模型网关、写入 CI 流程。如果这篇文章对你有帮助可以收藏备用。后续我也会持续更新 Claude Code 的实战技巧和避坑记录。 
长河君 · 2026/8/30 2:49:39 · 阅读 1.2k Claude Code 完全指南：从安装到实战的 AI 编程助手
之前第一次折腾 Claude Code 时我其实是有点懵的npm 装完发现claude命令找不到登录完又提示组织账号没权限项目文件倒是能读但稍微复杂一点的生成逻辑总是靠现写提示词硬撑。后来把安装、认证、配置、会话管理和 Skills 扩展逐个捋顺之后才真正把它当成了主力生产力工具。这篇文章想按“从 0 到 1”的顺序把 Claude Code 的安装方式、登录认证、配置体系、常用命令、进阶玩法、常见报错排查和工程实践完整讲一遍。不管你是刚接触 AI 编程助手的新手还是已经在用其他 AI 工具、想评估对比的开发者都可以直接照着操作。1. Claude Code 是什么为什么值得学1.1 一句话理解Claude Code 是 Anthropic 推出的 AI 编程代理工具它不是一个网页聊天框而是跑在你的终端、IDE 和桌面应用里的一个“编码 Agent”。简单说你可以在命令行里直接对它下达任务阅读项目代码修改某个文件写单元测试提交 Git分析报错生成技术文档。它会根据当前项目的文件内容、命令输出和你的指令自主地调用工具、读取代码上下文并完成多步操作。也就是说它不只是“帮你补全代码片段”而是“帮你在项目里干活”。1.2 它能解决什么问题传统 AI 对话工具最大的问题是“上下文脱离项目”。你复制一段代码进去它只能泛泛地分析但它看不到整个项目的目录结构、依赖关系、最近改动。Claude Code 解决的是这类问题修改一个功能时能自动关联相关文件和调用链阅读大型项目时不用手动把十几个文件一个个贴进对话执行测试或命令后能读取输出结果并根据报错继续调整需要重复执行的项目规范、代码风格、提交格式可以通过项目配置固化下来。所以它更适合用在真实项目开发、代码重构、技术文档维护、复杂问题定位等场景而不是简单的“写个 Python 爬虫”“生成一段排序代码”。1.3 CLI、桌面版和 VS Code 插件的关系Claude Code 目前有几种常见形态很多人容易搞混。CLI 命令行工具核心形态。在终端中执行claude命令启动几乎全平台可用也是后续 VS Code 插件和桌面版依赖的基础。VS Code 插件适合习惯在编辑器里工作的开发者。安装插件后可以在编辑器中唤起 Claude Code 面板选区代码直接提问查看 diff 等。桌面版Claude Desktop一种带图形界面的运行环境适合不想频繁操作终端、又想用 Claude Code 管理项目的人。在开始之前建议先理解无论哪种形态底层使命是一致的都是“让 AI 进入你的工程项目”。如果你只是日常开发终端 CLI 加 VS Code 插件基本就够用了。2. 环境准备与安装方式2.1 安装前的环境要求Claude Code 的版本迭代比较快所以下面这些版本只是“基础要求”具体请以官方最新说明为准操作系统Windows、macOS、Linux 均可但不同平台在终端命令上略有差异。Node.js官方主要推荐通过 npm 安装所以需要先装 Node.js建议使用 LTS 版本。包管理器npm 会随 Node.js 一起安装也可以使用 pnpm、yarn 等替代。终端Windows 建议使用 PowerShell 7 或 Windows TerminalmacOS 使用自带 Terminal 或 iTerm2 均可。如果你的机器上还没有 Node.js建议先到 Node.js 官网安装 LTS 版本。安装完成后在终端里执行node -v npm -v能正常输出版本号就说明 Node.js 环境没有问题。2.2 使用 npm 安装 CLICLI 是 Claude Code 的核心。安装命令很简单npm install -g anthropic-ai/claude-code执行之后npm 会下载并全局安装 Claude Code。安装完成后验证是否成功claude --version如果此时提示找不到命令常见原因有两个npm 全局安装目录没有加入系统 PATH安装过程因为网络或权限问题中断。Windows 下可以检查 npm 全局目录npm config get prefix确认该目录是否在你系统的环境变量PATH中。如果还不确定可以重新执行一次安装并留意终端里的安装日志。2.3 安装 VS Code 插件如果你习惯在 VS Code 中开发推荐再安装官方插件。安装步骤打开 VS Code点击左侧扩展图标搜索关键词Claude Code找到对应插件点击 Install重启或重新加载窗口。安装完成后VS Code 左侧或命令面板中会出现 Claude Code 相关入口。通过插件你可以把选中的代码发送给 Claude Code也可以直接让它分析当前打开的文件、生成测试、修复 lint 错误等。注意VS Code 插件通常会调用本机的claude命令行工具。也就是说即使装了插件也建议先完成 CLI 的安装。2.4 桌面版与内置终端除了 CLI 和 VS Code 插件Claude Code 桌面版也在逐步流行。桌面版本质上仍会依赖本地的 Claude Code 运行环境只是外面包了一层图形界面适合用来管理多个项目、查看任务历史。如果你在桌面版中遇到类似claude app host claude code binary not available的提示大概率是本地没有完整安装 CLI或者桌面版没有找到 CLI 的下载路径。此时优先回到命令行把 CLI 装好再重启桌面版。2.5 验证安装安装完成后可以运行一个最简单的命令确认 Claude Code 能正常响应claude 你好请介绍一下你自己如果启动了交互界面并等待继续输入说明基本可用如果提示需要登录请看下一节认证内容。3. 登录认证与配置体系3.1 登录认证方式Claude Code 首次使用时需要完成账号认证。运行claude终端通常会显示一个授权链接通过浏览器登录账号并授权后终端会自动完成认证。这种方式属于 OAuth 登录适合个人账号日常使用。如果你使用的是企业或组织账号登录时可能遇到类似提示your organization has disabled claude subscription access for claude code意思是当前组织没有开放 Claude Code 权限。这种情况不是本机配置问题需要找组织管理员在后台开启相关权限。3.2 使用 API Key 配置很多开发者会在团队或自动化场景中使用 API Key 而不是 OAuth 登录。这时可以通过环境变量或配置文件指定。终端临时指定export ANTHROPIC_API_KEY你的 API Key claude如果把 API Key 写到配置文件里可以避免每次启动都设置环境变量。Claude Code 的配置文件位于~/.claude/settings.json里面可配置环境变量、默认模型、权限等。示例{ env: { ANTHROPIC_API_KEY: 你的 API Key } }配置完成后重启 Claude Code 即会生效。需要注意不要把包含真实 API Key 的文件提交到 Git 仓库。3.3 项目级指令文件 CLAUDE.mdCLAUDE.md是 Claude Code 最值得学习的配置之一。它相当于项目的“给 AI 看的说明文档”。当 Claude Code 进入一个项目时它会自动读取根目录下的CLAUDE.md把它当作最重要的项目上下文。也就是说你不需要每次对话都重复“我们这个项目是 Java 项目”“接口要返回统一结构”把这些规则写进CLAUDE.md就行。示例CLAUDE.md# 项目说明 这是一个 Spring Boot 3 项目使用 Maven 构建Java 版本为 17。 # 常用命令 - 构建mvn clean package - 测试mvn test - 启动mvn spring-boot:run # 代码规范 - 所有 Controller 返回值使用 Result 包装类 - 数据库操作必须通过 Mapper 层禁止在 Service 中直接写 JDBC - 日志使用 slf4j禁止使用 System.out有了这份文件后Claude Code 在生成代码、修改代码时会主动遵循这些规则。除了项目根目录你也可以在用户全局目录~/.claude/CLAUDE.md中写一些跨项目的个人偏好比如“默认回答使用中文”“不要生成多余注释”等。3.4 Settings 文件详解Claude Code 支持多级配置理解文件层级对团队协作非常重要。~/.claude/settings.json用户级全局配置对所有项目生效。.claude/settings.json项目级共享配置建议提交到 Git 仓库团队统一使用。.claude/settings.local.json项目级个人配置一般加入.gitignore不提交。常见配置项包括model默认使用的模型env环境变量比如 API Key、Base URLpermissions权限规则控制 Claude Code 可以执行哪些命令、读写哪些文件hooks钩子脚本在执行特定动作前后触发自定义逻辑includeCoAuthoredByGit 提交时是否附上 AI 协作署名等。示例.claude/settings.json{ model: claude-sonnet-4-5, permissions: { allow: [ Bash(npm run lint), Read(.) ], deny: [ Bash(rm -rf *) ] } }注意权限字段的具体写法和可用值会随版本变化建议以当前版本的帮助文档为准。关键是理解“允许什么、拒绝什么”的配置思想。3.5 目录结构总结用一段时间后你可能会在项目里看到这些文件和目录my-project/ ├── .claude/ │ ├── settings.json │ ├── settings.local.json │ └── skills/ ├── CLAUDE.md └── ...用户本机还会看到~/.claude/ ├── CLAUDE.md ├── settings.json ├── skills/ └── ...弄清楚这些目录的作用后面配置 Skills、切换模型时就不会迷路。4. 核心使用方式从命令行到多模式实战4.1 启动交互模式安装并认证完成后最直接的使用方式是在项目目录下运行claude进入交互模式后你可以像聊天一样输入指令。比如请帮我看看当前项目的目录结构并解释每个模块的作用。Claude Code 会读取文件并回答。如果你想让它修改代码要尽量给出清晰的边界例如把 utils/date.js 里的 formatTime 函数重构一下要求支持时区参数保留原有导出名并补上单元测试。在交互模式中还可以使用/help查看所有可用斜杠命令使用/model查看和切换模型。4.2 非交互命令模式如果不需要进入交互界面只想一次性提交任务可以使用-p参数也就是 print / 非交互模式claude -p 分析当前项目的 package.json列出所有生产依赖非交互模式适合写脚本、接入 CI/CD 流程。比如claude -p 根据 CHANGELOG.md 的模板生成本周版本更新说明 --output-format text在自动化脚本中可以捕获输出后继续处理。4.3 会话恢复与继续Claude Code 的会话是可以保存的。如果你在一次长对话中关闭了终端之后可以继续。相关参数# 继续上一个会话 claude --continue # 恢复某个历史会话 claude --resume当你需要分阶段处理同一个任务时恢复会话能让 AI 继续保留之前的项目上下文不用从头解释。4.4 斜杠命令与常用操作交互模式下常用斜杠命令包括/help查看帮助/clear清空当前会话上下文/compact压缩上下文减少 token 占用/cost查看当前会话费用消耗/model切换模型/logout退出登录。我个人的习惯是当对话历史太长、AI 开始“忘事”时先执行/clear重新整理一次任务描述或者把关键结论写进项目文档再让 Claude Code 读取而不是一味延长对话。4.5 VS Code 插件实战VS Code 插件的常见操作流程打开项目选中最想提问的代码块右键选择 Claude Code 相关命令在输入框中描述需求例如“为选中函数补充 JSDoc 注释”插件会调用 Claude Code 生成修改建议并显示 diff确认后应用修改。这种方式比“复制代码到网页聊天框”高效得多因为插件能感知当前文件、选区、打开的其他文件上下文损失最小。5. 进阶玩法Skills、切换模型与文档生成5.1 Skills 技能包Skills 是 Claude Code 的一项扩展机制。你可以把它理解成给 AI 预装的“插件技能”。比如代码审查技能Git 提交信息生成技能数据库迁移脚本技能技术写作技能。Skills 一般以目录形式存在常见位置包括用户级~/.claude/skills/和项目级.claude/skills/。每个技能目录里通常包含一个描述文件例如SKILL.md用于说明该技能的用途、触发方式和参数。使用技能时Claude Code 会在合适的场景自动加载或通过/skills查看当前可用的技能列表。安装 Skills 的常见方式从 Git 仓库克隆技能包把技能目录复制到.claude/skills/重启 Claude Code 并验证。由于 Skills 社区发展很快不同技能包的安装要求差异较大建议优先使用有明确文档和示例的技能包。5.2 配置第三方模型服务Claude Code 原生主要面向 Anthropic 的模型服务。但不少团队会使用兼容 Anthropic API 格式的模型网关或者通过 OpenRouter 这类聚合服务接入其他模型。此时可以设置环境变量或配置文件{ env: { ANTHROPIC_BASE_URL: https://你的模型网关地址, ANTHROPIC_MODEL: 你使用的模型名, ANTHROPIC_API_KEY: 你的 API Key } }也有社区工具比如 cc-switch本质上就是帮助你快速管理和切换上面这几个配置项避免每次手工改settings.json。需要特别注意配置第三方模型服务时模型名必须是当前模型网关真实可用且能提供完整能力的模型名。如果写错可能遇到类似deepseek-v4-pro is not a model this version of claude code recognizes这个报错的含义是Claude Code 识别到了你配置的模型名但它不认可或当前环境不支持。排查时优先核对模型名是否正确网关地址是否正确当前 Claude Code 版本是否支持该模型网关是否兼容 Claude Code 依赖的 API 格式。5.3 用 Claude Code 写技术文档Claude Code 非常适合生成和维护技术文档。很多人在写文档时最痛苦的是“文档跟不上代码”而 Claude Code 可以直接读代码、读注释、读测试然后帮你生成文档初稿。例如在项目根目录执行claude -p 阅读 src 目录下的接口代码生成一份 API 文档包含接口路径、请求参数、返回结构输出到 docs/api.md它也能帮你维护 README根据当前项目的启动方式、环境变量、测试命令重新整理 README.md要求结构清晰。注意AI 生成的文档仍然需要人工核对尤其是涉及安全、权限、复杂业务逻辑的部分。文档生成后一定要让熟悉业务的同事 review。6. 常见问题与排查思路6.1 安装类问题问题现象常见原因解决思路claude 不是内部或外部命令npm 全局目录不在 PATH 中检查 npm 全局目录并加入 PATH安装缓慢或中断网络不稳定检查网络后重试或切换 npm 镜像源版本更新后功能异常旧版本缓存执行 claude --update 或重新安装6.2 认证与权限类问题问题现象常见原因解决思路登录后提示无订阅权限当前账号没有 Claude Code 访问权限检查账号订阅或联系管理员组织账号无法使用组织后台禁用了 Claude Code由管理员开启对应权限API Key 认证失败Key 失效或权限不足检查 Key 是否有效权限是否匹配6.3 模型配置类问题看到类似xxx is not a model this version of claude code recognizes报错按以下顺序排查执行claude --version确认当前版本执行/model或在配置文件中查看当前模型名确认模型名是否真实存在于你使用的模型服务中如果使用了第三方网关确认网关地址能正常访问、接口兼容 Anthropic 格式修改配置后重启 Claude Code。6.4 请求类错误问题现象常见原因解决思路429 / 529 错误请求过于频繁或服务繁忙稍后重试降低请求频率响应突然中断网络波动或超时检查网络并尝试恢复会话上下文过长单轮对话 token 超限使用 /compact 压缩或 /clear 重开遇到 529 时我最推荐的做法不是立刻换模型而是先停止并发任务等 1 到 2 分钟再重试避免反复触发限流。7. 最佳实践与工程建议7.1 项目指令先行不要让 Claude Code“猜”你的项目规则。在项目启动前先写好CLAUDE.md把技术栈、命令、代码规范、目录职责写清楚。这样可以显著提升 AI 生成代码的质量减少无效修改。7.2 最小权限原则Claude Code 能执行命令、读写文件但也意味着风险。生产环境、敏感目录、数据库操作都必须遵循最小权限原则不要让 Claude Code 默认拥有全部权限在permissions中显式允许、拒绝关键命令涉及删除、数据库变更、生产发布的命令先人工审查再手动或经授权执行。我的建议是高风险命令默认拒绝确需执行时再临时授权而不是一次性全部放行。7.3 会话与上下文管理AI 的上下文窗口是有限的。长会话会越来越慢也容易“遗忘”。合理做法每个任务独立会话不要把所有需求堆在一个会话里任务复杂时把需求、约束写进文档让 Claude Code 读取而不是反复追加提示词关键结论要沉淀到CLAUDE.md或项目文档中方便后续会话复用。7.4 安全边界Claude Code 生成的代码不一定天然安全。它写 SQL 时可能漏掉 WHERE 条件写命令时可能误操作文件。因此涉及数据库、鉴权、支付等敏感逻辑必须人工 review任何删除、批量更新、生产环境变更先备份、先测试不要把真实密钥写进项目文件或持久化到 Cloude Code 配置中。7.5 团队协作建议如果团队多人使用 Claude Code可以把以下文件纳入版本管理.claude/settings.json统一团队工具行为CLAUDE.md统一项目背景和代码规范docs/下的 AI 生成文档作为人工 review 后的沉淀产物。同时要把.claude/settings.local.json、.env、包含密钥的文件加入.gitignore避免隐私泄露。8. 总结与下一步规划这套从安装到实战的流程走下来你应该已经掌握了 Claude Code 的安装、登录、配置、交互模式、非交互模式、Skills、模型切换、文档生成和常见问题排查。核心要点可以总结为三句话先装好 CLI再配 VS Code 插件和桌面版用CLAUDE.md和settings.json把项目背景、权限边界固化下来把 Claude Code 当成“有上下文的编程助理”而不是一次性问答工具。接下来的学习路线建议先从自己的真实项目开始每天挑一个小任务交给它例如“补充单元测试”“重构一个函数”“生成接口文档”。等熟悉了它的行为边界再逐步尝试配置 Skills、接入团队模型网关、写入 CI 流程。如果这篇文章对你有帮助可以收藏备用。后续我也会持续更新 Claude Code 的实战技巧和避坑记录。