之前一直在折腾 AI 编程工具坦白说 Claude Code 是我用过的工具里最接近“项目级助手”的一个。但很多人在安装和配置阶段就被卡住了尤其是想把底层模型换成 Deepseek、想在 VSCode 里稳定使用、想让 Skill 真正生效的场景网上资料东一块西一块没有一个能从头跟到尾的完整流程。这篇文章围绕 Claude Code 的安装、Deepseek 模型接入、VSCode 集成、Skill 实战四条主线展开。内容包括完整命令、配置片段、可运行的示例代码以及我实际使用中遇到的高频问题和排查方法。无论你是刚接触 AI 编程工具还是已经用过一段时间但卡在模型接入上都可以按顺序照着做一遍。1. 背景与核心概念1.1 Claude Code 到底是个什么工具Claude Code 是 Anthropic 推出的命令行 AI 编程 Agent。如果你只把它理解成一个“在终端里聊天的大模型”那就低估它了。它真正核心的能力是端到端执行开发任务。启动之后它会扫描当前项目目录读取文件结构、Git 状态、代码内容然后根据你提出的需求自主拆解任务、调用工具、修改文件、执行命令。比如你可以直接对它说“帮我给这个项目补一个单元测试跑一遍现有测试把失败的原因列出来。”它会先看懂项目使用的语言和测试框架然后找到相关源码编写测试文件再运行测试命令最后把结果反馈给你。这个过程中它不是单纯生成文本而是在真实地操作你的项目。很多第一次接触 Claude Code 的开发者会拿它和 GitHub Copilot 对比。Copilot 的核心场景是补全和短问答在你写代码时提供建议Claude Code 则是一个能独立完成子任务的 Agent它会维护一个任务计划逐步执行并在关键节点停下来等你确认。1.2 为什么国内开发者关注它Claude Code 默认情况下连接 Anthropic 的官方服务使用门槛比较高。对于国内开发者来说更常见的做法是保留 Claude Code 的 Agent 工具能力把底层模型切换到国产大模型比如 Deepseek。这个思路的本质是把“AI 前端工具”和“大模型服务”彻底解耦。Claude Code 本身支持通过环境变量指定模型接口地址Deepseek 又提供了 Anthropic 兼容接口于是两者可以组合使用。你不需要改动 Claude Code 的任何代码只需要把接口地址和密钥配置到位。这种组合还有一个好处模型生态变化很快今天用 Deepseek明天可能想试别的模型。只要配置层面保持解耦切换模型时改几个环境变量就够了Skill、项目上下文、工作流都可以继续复用。1.3 Skill 是什么Skill 是 Claude Code 里的“技能包”用来把某一类任务的执行规则固化下来。举个例子如果你经常需要做代码审查要求检查命名规范、异常处理、安全风险、性能隐患并且输出固定格式的审查报告。你当然可以在每次提问时把这一大段要求重新描述一遍但这很累而且每次描述的详细程度还不一样。用 Skill 的方式你只需要在项目里新建一个技能目录写一个 SKILL.md 文件把审查规则、输出格式、注意事项全部写进去。之后只要在对话中提到“审查代码”Claude Code 就会自动加载这个 Skill按照里面的规则执行。这相当于给 AI 助手定义了一套可复用的 SOP。对于团队协作来说Skill 的价值更明显。把代码规范、测试要求、发布检查清单固化到 Skill 文件里所有成员用同一个 AI 工具时行为输出就会保持一致而不是完全依赖每个人的提问水平。2. 环境准备与版本说明2.1 基础环境要求在实际操作前先确认你的机器满足基本条件。Claude Code 通过 npm 安装所以 Node.js 是必须的。如果你还没有安装可以从 Node.js 官网下载 LTS 版本如果已经安装了其他版本先确认一下版本号node -v npm -v建议使用 Node.js 18 或更新的 LTS 版本。版本太老可能会出现兼容性问题安装包也比较陈旧。操作系统方面Windows 10/11、macOS、常见 Linux 发行版都可以。终端工具建议使用 Windows Terminal 或 PowerShellmacOS 用户直接用系统终端即可。如果你后面要在 VSCode 里使用直接在集成终端中运行命令即可。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。不同 Node.js 版本会带来细微差异但核心配置流程是通用的。2.2 配置 Node.js 国内镜像安装 Claude Code 最常用的方式是 npm 全局安装。如果你在国内网络环境下执行 npm install 时经常遇到超时、卡顿第一步就是把 npm 默认源切换为国内镜像。这里以常用的 npmmirror 为例npm config set registry https://registry.npmmirror.com配置完成后验证一下是否生效npm config get registry如果输出结果指向你设置的镜像地址说明配置成功。这一步能显著提升 npm 包的下载速度和稳定性。需要说明的是镜像源解决的是 npm 安装包下载慢的问题。后续使用 Deepseek 接口时请求是否稳定取决于你选的模型服务本身的网络情况两者没有直接关系。2.3 安装 Claude CodeClaude Code 官方支持多种安装方式这里推荐两种。方式一npm 全局安装适合所有平台npm install -g anthropic-ai/claude-code安装完成后检查命令是否可用claude --version如果输出版本信息说明安装成功。方式二使用官方安装脚本适合 macOS / Linuxcurl -fsSL https://claude.ai/install.sh | bashWindows 下不建议用安装脚本直接用 npm 方式更稳定。安装完成后如果提示claude: command not found但在 npm 安装时没有报错通常是 Node.js 全局 bin 目录没有加入系统 PATH。这个问题的处理方式会在第 7 章详细说明。3. 接入 Deepseek 模型3.1 为什么要换成 DeepseekClaude Code 默认连接 Anthropic 官方接口对于国内开发者来说账号注册、模型访问、支付都存在一定门槛。Deepseek 作为国产大模型在接口稳定性和成本上有明显优势。更关键的一点是Deepseek 提供了 Anthropic 兼容接口。Claude Code 通过环境变量指定接口地址和鉴权 Key就能把底层模型切换为 Deepseek。工具本身的任务编排、文件操作、命令执行能力完全保留只是模型推理从原来的官方模型变成 Deepseek 的模型。需要提醒的是Claude Code 的最终表现既取决于 Agent 工具本身也取决于所选模型的推理水平。接入 Deepseek 后代码生成质量、复杂任务拆解能力会与 Deepseek 模型的实际表现密切相关。所以不要指望换个模型地址就能获得和原版完全一致的体验建议先用测试任务对比一下再决定是否长期使用。3.2 获取 Deepseek API Key使用 Deepseek 接口前需要到 Deepseek 开放平台完成注册然后在控制台创建 API Key。创建 API Key 时有几个细节要特别注意第一API Key 只在创建页面完整展示一次离开页面后就无法再次查看必须立刻保存到安全的位置。第二API Key 是敏感凭证不要提交到 Git 仓库不要贴在聊天群里也不要写在项目代码里。第三如果你怀疑 Key 已经泄露不要单独修改直接去控制台删除并重新生成。保存 Key 时建议建立一个本机的环境变量管理习惯而不要散落在多个配置文件里。这里推荐一种常见做法把 Key 写入本机的 shell 配置文件或者使用 direnv 之类的工具按目录加载 .env 文件。3.3 配置环境变量Claude Code 通过两个关键环境变量切换模型接口ANTHROPIC_BASE_URL模型接口的基础地址。ANTHROPIC_AUTH_TOKEN用于接口鉴权的 API Key。在终端里临时设置export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的Deepseek API Key部分环境中还需要指定模型名称可以同时设置export ANTHROPIC_MODELdeepseek-chat这里要注意不同版本的 Claude Code 对模型名称环境变量的支持不完全一致。如果你设置后没有生效需要查阅你所安装版本的官方文档确认是否使用ANTHROPIC_MODEL、CLAUDE_MODEL或其他变量名。为了避免每次打开终端都手动设置一遍建议把环境变量写入 shell 配置文件。macOS / Linux 用户编辑~/.zshrc或~/.bashrcWindows 用户可以在系统环境变量中添加或者在 PowerShell 配置文件中设置。编辑完成后重新加载配置source ~/.zshrc3.4 验证配置是否生效在项目目录下启动 Claude Codeclaude进入交互界面后输入一句最简单的指令“请介绍一下当前目录下的项目结构。”如果 Claude Code 能返回项目结构说明说明模型接口已经接通。如果返回鉴权失败、404、超时等错误先不要着急第 7 章有完整的排查流程。这里有件事要提前说清楚Claude Code 启动后会维护一个会话上下文。第一次启动、首次输入指令时它需要时间处理项目扫描和模型响应所以不要因为第一次响应慢就认为卡死了。4. 在 VSCode 中使用 Claude Code4.1 两种使用方式在 VSCode 里使用 Claude Code常见的有两条路。第一条是直接在集成终端中运行claude命令。这种方式最简单不需要安装额外插件。集成终端天然共享 VSCode 当前打开的工作目录所以 Claude Code 能直接读取项目文件操作项目的视角和你手工操作终端完全一致。第二条是安装 VSCode 扩展。官方和社区都有相关扩展但插件版本更新比较快功能差异也比较大。如果你不想折腾插件在集成终端中使用已经完全够用。如果你追求图形界面和状态展示可以到扩展市场搜索 Claude Code选择下载量较高、维护活跃的扩展。我个人的建议是先使用集成终端方式把核心流程跑通再逐步尝试扩展功能。4.2 在集成终端中初始化项目假设你有一个 Python 项目路径是~/projects/demo。打开 VSCode 后通过菜单 Terminal - New Terminal 打开集成终端执行cd ~/projects/demo claudeClaude Code 启动后会扫描当前工作目录。如果项目里有 Git 初始化记录它会自动识别版本库信息后续涉及 Git 操作时就能直接使用。我第一次在新项目中启动 Claude Code 时通常会先执行/init命令。这个命令会让 Claude Code 读取整个项目生成一份CLAUDE.md项目说明文件。这个文件会记录项目的技术栈、目录结构、常用命令、构建方式等信息后续每次对话它都会参考这份文件。维护好CLAUDE.md是提升 Claude Code 输出质量最重要的手段之一。4.3 常用命令一览在 Claude Code 交互界面里有几个高频命令值得提前记住/init让 Claude Code 读取项目并生成CLAUDE.md项目说明文件。/compact压缩当前对话上下文当对话过长、模型开始“忘事”时使用。/clear清空当前对话开启一个全新会话。/help查看所有可用命令。这些命令的价值在长时间使用后会更明显。一个会话如果持续太久上下文窗口会接近上限模型回答质量会下降。此时执行/compact压缩历史或者直接/clear开始新会话往往比继续追问更有效。5. Skill 实战5.1 Skill 的目录结构与格式Claude Code 的 Skill 约定放在项目根目录的.claude/skills下。每个技能对应一个子目录目录名建议使用短横线风格例如code-review、test-generator、python-best-practice。每个目录里至少包含一个SKILL.md文件。一个最小 Skill 的目录结构如下my-project/ └── .claude/ └── skills/ └── code-review/ └── SKILL.mdSKILL.md采用 Markdown 格式头部是 YAML frontmatter用来声明技能元信息。最小示例--- name: code-review description: 对指定文件进行代码规范审查输出问题清单与修改建议。当用户提到 review、审查、代码检查时使用。 ---description这一段非常关键。Claude Code 会先阅读所有 Skill 的描述再根据当前用户需求判断该加载哪个技能。描述里的触发词写得越清晰技能被准确调用的概率越高。比如上面这个示例里“审查”“代码检查”“review”都是触发词。5.2 编写一个完整的 Code Review Skill下面是一个可以直接用于实际项目的 Code Review Skill 示例。除了 frontmatter正文里定义了技能的执行规则、检查维度和输出格式--- name: code-review description: 对指定代码文件进行规范审查。当用户要求 review、检查代码、代码审查时使用。 --- # Code Review 技能 执行步骤 1. 读取用户指定的目标文件。 2. 按以下维度检查可读性、命名规范、异常处理、安全风险、性能隐患。 3. 输出审查结果。 输出格式 - 文件路径 - 问题严重级别高 / 中 / 低 - 问题描述 - 修改建议 额外要求 - 不使用攻击性或模糊语言。 - 每个问题必须给出具体行号或代码片段。注意Skill 的正文不一定需要写代码而是写“规则”。Claude Code 会把 SKILL.md 的内容注入上下文作为执行该任务时的系统提示。所以规则越具体输出就越稳定。比如你在规则里写“每个问题必须给出具体行号”模型就会在输出中尽量带上行号如果你不写它可能只给出一段泛泛的评价。5.3 触发 Skill 的三种方式在 Claude Code 里Skill 的触发方式主要有三种。方式一自动触发。用户输入内容与description中的触发词匹配时模型会主动加载对应技能。适合高频通用技能。方式二显式指定。输入中带技能名例如请使用 code-review 审查 src/main.py这种方式适合关键任务能避免模型选错技能。方式三在会话中直接描述要启用的能力。比如“接下来按团队规范执行代码审查”。这种方式适合技能列表较多、需要切换上下文的场景。实际项目中我更推荐第二种方式。显式指定技能名输出结果更可控。5.4 验证 Skill 是否生效写好 Skill 后在项目目录下启动 Claude Code输入“帮我审查一下 src/main.py”如果输出结果符合SKILL.md中定义的格式说明技能生效。如果输出和普通对话没有区别按下面的顺序检查第一步确认文件路径是否正确。Skill 必须放在.claude/skills/技能名/SKILL.md路径不对就不会被扫描到。第二步检查 frontmatter 语法。name不能包含空格description必须写清楚。第三步确认触发词是否明确。如果 description 里只写了“代码审查”但用户说的是“review”可能匹配不上。6. 代码实战用 Claude Code 生成一个小工具6.1 项目需求为了验证整套流程这里做一个简单但完整的实战用 Python 写一个批量文件重命名工具。需求如下读取指定目录下所有 JSON 文件。把文件名中的临时前缀tmp_去掉。输出每次重命名后的前后对照。选择这个需求是因为它足够简单适合第一次跑通流程又涉及文件读写和异常处理能真正看到 Claude Code 的代码生成能力。6.2 让 Claude Code 生成代码在项目目录下启动 Claude Code输入“请编写一个 Python 脚本读取指定目录下所有 JSON 文件去掉文件名中的 tmp_ 前缀并输出重命名对照表。”Claude Code 会生成类似下面的脚本# 文件路径rename_json.py import os from pathlib import Path def rename_json_files(directory: str .) - None: 去掉指定目录下 JSON 文件名中的 tmp_ 前缀。 directory_path Path(directory) if not directory_path.exists(): print(f目录不存在: {directory_path}) return renamed_count 0 for file_path in directory_path.glob(tmp_*.json): new_name file_path.name.replace(tmp_, , 1) new_path file_path.with_name(new_name) try: file_path.rename(new_path) print(f{file_path.name} - {new_name}) renamed_count 1 except OSError as e: print(f重命名失败: {file_path.name}原因: {e}) if renamed_count 0: print(没有找到需要重命名的 JSON 文件。) if __name__ __main__: rename_json_files()这里要特别提醒Claude Code 生成的代码不一定完全符合你的预期但它通常是一个可运行的基础版本。生成后你需要通读一遍确认逻辑符合需求再执行。尤其涉及文件批量操作时建议先在小范围内测试不要在正式目录里直接跑。6.3 运行与验证创建一个测试目录手工制造几个带前缀的文件mkdir -p test_files cd test_files echo {id: 1} tmp_a.json echo {id: 2} tmp_b.json echo {id: 3} normal.json cd .. python rename_json.py预期输出tmp_a.json - a.json tmp_b.json - b.json 没有找到需要重命名的 JSON 文件。如果你指定目录运行python rename_json.py test_files同样可以完成批量重命名。整个过程里Claude Code 先读懂需求再生成代码。如果生成结果有误你可以继续在对话里补充细节比如“只处理当前目录、不递归子目录”“遇到同名文件要跳过”“先打印计划不实际执行”。这些约束条件都会影响最终代码。6.4 让 Skill 参与实战在上面这个任务中如果项目里已经有一个python-best-practice的 Skill里面定义了 Python 代码规范你可以在输入时显式指定“请使用 python-best-practice 编写一个批量重命名 JSON 文件的脚本。”Claude Code 会按照 Skill 中的代码规范生成脚本输出会带类型注解、异常处理、docstring 等元素。这就是 Skill 在实际项目中的价值把团队规范固化到工作流里而不是依赖模型随机的审美。7. 常见问题与排查思路7.1 常见问题表格下面按问题现象、常见原因、解决思路三个维度整理方便你快速定位。问题现象常见原因解决思路claude 命令找不到Node.js 全局 bin 不在 PATH 中或 npm 安装失败确认 node、npm 可用重新执行 npm install -g把全局 bin 目录加入 PATHnpm 安装卡住或超时默认源下载慢或网络不稳定配置 npm 国内镜像后重新安装启动 claude 后鉴权失败ANTHROPIC_BASE_URL 或 ANTHROPIC_AUTH_TOKEN 配置错误检查环境变量是否生效确认 API Key 前后无空格核对接口地址请求超时或返回 404模型接口地址写错模型名称不支持参考官方文档修正接口地址更换支持的模型名称Skill 不生效SKILL.md 路径错误或 frontmatter 语法错误确认文件在 .claude/skills 下检查 name 和 description 格式生成的代码不符预期需求描述不够具体上下文信息不足补充目录范围、代码风格、安全约束等条件对话太长后回答质量下降上下文窗口接近上限使用 /compact 压缩上下文或 /clear 开启新会话7.2 排查环境变量的标准流程当你发现 Claude Code 连接不上模型时按下面的顺序排查。第一步确认环境变量已经加载。在终端执行echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN如果没有输出说明变量没有写入当前 shell或者写入的配置文件没有被加载。第二步临时在命令行里手动设置一遍排除 shell 配置文件的问题export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的Key第三步用 curl 测试接口连通性curl https://api.deepseek.com/anthropic如果返回 404 或 401说明域名可达问题出在鉴权信息或接口路径如果请求直接超时先检查本地网络环境能不能稳定访问该服务。第四步确认 API Key 的权限范围。部分 Key 可能只支持特定模型或特定接口需要到控制台查看你创建 Key 时勾选的权限。7.3 如何避免踩坑把这些高频问题的预防措施总结一下环境变量统一放在 shell 配置文件或 .env 文件中不要每次手动 export。API Key 加入 .gitignore避免误提交到 Git 仓库。在正式项目里使用 Skill 前先在测试目录跑通一次。批量文件操作类任务先做少量样本验证。定期关注 Claude Code 和 Deepseek 接口的版本更新配置格式可能会变。8. 最佳实践与工程建议8.1 项目上下文管理Claude Code 是一个对上下文高度敏感的工具。项目根目录下的CLAUDE.md是它理解项目的重要入口。建议你在项目初始化时执行/init生成这个文件并定期维护。CLAUDE.md 中可以写清楚项目的技术栈和编程语言。目录结构说明。常用构建、测试命令。代码风格约定。禁止执行的操作例如不允许直接删除数据库数据、不允许修改生产环境配置。这些信息会让 Claude Code 生成的代码更贴合你的项目而不是每次从零猜测。比如你明确写了“数据库连接串统一放在 .env 文件”它生成代码时就会主动使用os.getenv而不是硬编码。8.2 凭证与安全边界使用 API Key 时遵循最小权限原则。如果你只在某个项目里使用 Deepseek 接口不要让 Key 拥有不必要的权限范围。环境变量文件只保存在本机不要把 Key 复制到共享文档。如果 Claude Code 被要求在项目中执行高危操作例如删除文件、操作数据库、推送代码建议在关键操作前人工确认。虽然 Claude Code 本身有权限提示机制但工程上仍然要设置安全护栏生产环境操作必须走审批流程不能在 AI 工具里直接发起。一个比较实用的做法是在 CLAUDE.md 中明确写出禁区禁止执行的操作 - 禁止删除 data 目录下的任何文件。 - 禁止直接执行 git push 到 main 分支。 - 禁止修改生产环境配置文件。这样 Claude Code 在执行过程中会主动避开这些危险动作。8.3 Skill 的迭代方法Skill 不是写一次就结束的。建议按下面的节奏持续迭代。第一先写一个最小 Skill跑通流程。不要一开始就追求覆盖所有场景。第二在实际使用中记录模型输出不符合要求的地方补充到 SKILL.md 的规则里。比如发现生成的代码总是不写异常处理就在规则里加一条“所有文件读写必须包含 try/except 和明确的错误提示”。第三把多个相关规则归类拆分成更细的 Skill。例如单独拆分code-review、unit-test、log-format每个 Skill 保持单一职责。第四让团队成员共享同一套 Skill 仓库保证大家的行为一致。Skill 的维护本质上是在维护团队的“AI 工作规范”。8.4 性能与成本意识使用 Deepseek 模型时成本和上下文长度直接相关。长对话会消耗更多 token建议定期用/clear开启新会话。对于可重复执行的流程尽量写成 Skill 并给出明确步骤减少多余的上下文开销。在编写需求时措辞越精确模型就会少走弯路。不要一句话丢给工具就等结果而是把目标、范围、约束、输出格式一次说清楚。举例来说与其说“帮我优化一下代码”不如说“把 src/utils.py 里 read_file 函数的异常处理补全要求所有异常都带上文件名和具体错误信息并输出修改前后的 diff”。8.5 从工具使用者到流程设计者Claude Code 这类 AI 编程工具真正提升效率的前提是你已经想清楚团队的工作流程。工具负责执行你负责定义规则。在选择模型时不必盲目追求某个大模型的评测分数而要结合你的网络环境、成本预算、代码任务类型来选。Deepseek 是其中一个不错的选择但模型生态变化很快保持配置层面的解耦未来迁移新模型时只需要修改几个环境变量代码和 Skill 全部可以复用。“AI 编程工具 国产大模型 自定义 Skill”这套组合最值得花时间的部分不在安装而在你如何设计项目上下文、如何沉淀团队规范、如何让 Agent 在安全边界内高效执行任务。如果今天只记住三件事那就是先把 Claude Code 装好并接入 Deepseek然后在项目里执行/init生成上下文最后把高频重复的工作写成 Skill。接下来动手在自己的项目里试一次不用追求一次到位先让工具跑起来再逐步优化流程。遇到问题不要慌环境变量、路径、版本是三个最常用的排查方向对照表格逐项检查大部分问题都能解决。