简介这份资源是《Claude Code 使用手册》的配套源码包面向希望掌握 Claude Code CLI 的开发者尤其适合需要系统学习命令操作、Skill 编写与高级配置的中级及以上软件工程师。压缩包共 3 个文件主要包含一个 guide 说明文件、一个 HTML 页面以及一个 gitignore 配置文件其中 HTML 可用于在线查看手册内容gitignore 则方便用户在不同项目中直接复用忽略规则。目前已有 1603 人浏览学习适合快速上手并提升日常编码效率。手册内容覆盖快速入门、常用命令、Skill 创建与使用、多文件编辑、代码搜索分析、批量操作及个性化配置并附有常见问题排查方案。配置文件路径和常用配置项也做了明确说明阅读者可将源码包作为本地参考文档或二次整理基础按需修改配置后用于团队内部知识分享。1. 为什么用 Claude Code把 IDE、浏览器、终端三个窗口变成一个窗口写代码的时候最烦什么不是 bug 本身而是在 IDE、浏览器、终端三个窗口之间来回倒腾把报错复制出去贴给网页端模型等它思考完再把方案贴回来。Claude Code 把这一整条链路直接塞进终端里它能读你的项目文件、执行终端命令、根据命令输出继续决策是一个真正能上手干活的 AI 编码代理——不是聊天玩具是生产力工具。这份资源是 Claude Code 使用手册的源码形式发布覆盖安装、权限配置、模型接入与排错适合两类人一类是每天跟大量代码库打交道的后端和全栈工程师另一类是刚接触终端 AI 工具、想知道它到底能干到什么程度的开发者。想拿它当聊天窗口用也行但真正的价值在于把文件、命令、子进程组合起来让它独立完成读代码、跑验证、改文件、再跑验证的闭环。2. 从零安装到首次登录Windows 与 Ubuntu 两条路线的全部细节2.1 Windows桌面版和 npm 两条安装路径Windows 上装 Claude Code 有两条路。第一条是官方桌面版安装包图形界面点两下就装好适合不想碰命令行的用户装完自动把 CLI 二进制写进系统第二条更常用用 npm 全局安装适合本来就靠 Node 生态吃饭的开发者。我推荐第二条因为后续不管是升级版本还是切换模型 provider都在同一套命令行体系里操作不用在图形界面和终端之间反复横跳。# 全局安装 Claude Code CLI npm install -g anthropic-ai/claude-code # 验证安装是否成功 claude --version参数说明-g表示全局安装让claude命令在任意目录下都能直接调用。claude --version输出版本号这一步是验证 node 侧到 npm 侧再到 CLI 这条链路是不是通的。如果机器上同时装了多个 Node 版本-g装到哪个版本下claude命令就跟到哪个版本所以装完先跑which claude确认路径没有歧义。Windows 上比 Linux 多一个隐性坑如果以前装过旧版或者其他 AI 终端工具PATH 里可能残留同名可执行文件。装新版之前最好把旧的卸载干净不然claude命令调用的可能是个不知道哪来的老版本行为跟预期完全对不上。装完后在任意目录打开终端敲claude能进入交互界面就算初步成功。2.2 Ubuntu先把 Node 环境夯实Ubuntu 上安装失败十次里有八次不是 Claude Code 的问题而是系统自带的 Node 版本太低。Ubuntu 20.04 的 apt 源里默认 Node 只有 10.x而 Claude Code 对 Node 的引擎要求是 18 以上版本不够直接跑不起来。所以装 Claude Code 之前先把 Node 环境夯一遍。# 用 nvm 安装受支持的 Node LTS 版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 # 确认版本 node -v npm -v逻辑说明nvm install 20装的是 Node 20 LTS这个版本比 18 新但比 21 稳是当前绝大多数 CLI 工具兼容性最好的档位。source ~/.bashrc让 nvm 的 shim 立刻生效如果你用的是 zsh记得改成source ~/.zshrc不然 nvm 命令找不到。我习惯补一条nvm alias default 20否则新开一个终端 tab 又掉回系统旧版本到时候node -v和刚装的版本不一致排查起来非常绕。Node 环境就绪后npm 安装命令跟 Windows 完全一致。装完先claude --version验证再走下一步登录。2.3 首次登录与权限模型安装只是第一步登录才是真正入门的门槛。claude login会打印一个 URL浏览器打开后完成授权。这里有个容易忽略的点登录用的是你本机浏览器的账号会话如果浏览器侧有企业策略或隐私隔离授权页可能加载不出来换个普通浏览器或直接复制 URL 到无痕窗口往往就通了。# 在终端里启动登录流程 claude login # 登录成功后直接进入交互模式 claude比登录本身更重要的是理解它的权限模型。Claude Code 在项目里操作文件、执行命令前都会先征求你的同意。权限分三类allow放行、deny拒绝、ask每次都询问默认是ask。所有权限规则都写在settings.json里分全局和项目两级。{ permissions: { allow: [Read, Bash(npm run build)], deny: [Bash(rm -rf *)], ask: [Edit, WebFetch] } }参数说明这份配置放在项目根目录的.claude/settings.json只对当前项目生效全局配置放~/.claude/settings.json两者叠加项目优先级更高。Bash(npm run build)这种带具体命令的写法表示只针对这一条命令放行不会放开整个 Bash 权限。deny里的规则是硬边界Claude 无论如何都不会执行遇到rm -rf这类高危命令我建议每个人都提前写进 deny。3. 上手实操终端命令授权、斜杠命令与第三方模型接入的三个关键动作3.1 斜杠命令把高频操作固化成快捷方式Claude Code 提供一组斜杠命令直接在/后面敲几个字母就能触发。最常用的几个/clear清空当前会话上下文/compact压缩上下文防止 token 爆掉/init在项目里生成 CLAUDE.md/help快速查看所有可用命令。我每天真正离不开的是/init和/compact前者管项目认知后者管成本控制。/init之所以重要是因为它会扫一遍整个项目结构生成一个CLAUDE.md文件里面写了模块职责、构建命令、目录说明。后续每次会话 Claude 会自动加载这个文件不用再逐段解释项目背景。如果你刚拿到一个陌生代码库第一件事不是翻 README而是在项目根目录跑一次/init让 Claude 自己先建一份认知地图。/compact解决的是另一个问题上下文的窗口是有限的。对话太长了早期的重要信息会被挤掉Claude 开始答非所问。这时候/compact会把当前对话压缩成摘要保留关键决策和约束丢弃冗余内容相当于给会话做一次瘦身。3.2 让 Claude Code 直接执行终端命令这是 Claude Code 和普通聊天工具最大的分水岭它能直接在终端里跑命令、看到输出、再根据输出继续决策。比如让它跑完单测、看编译错误、执行 git 操作全程不用你复制粘贴。链路变成你下任务 → Claude 执行命令 → 读输出 → 改代码 → 再执行验证。但这条能力也是最需要管住的地方。它执行rm、git push这类有副作用的命令时如果权限放得太宽翻车是迟早的事。我一般先在settings.json里把权限收成白名单制再进会话派活。# 启动会话进入交互模式 claude然后直接在会话里下任务请运行 pytest tests/test_user_login.py -x如果失败了分析 traceback 并把修复写到对应源码里。执行过程中 Claude 会先跑pytest看到失败输出后自己去读test_user_login.py和被测模块的源码定位问题后直接改文件改完再跑一次验证。这套闭环就是AI 直接操作开发环境的实景。关键在于权限边界deny掉的命令它碰都不碰ask的每次弹窗确认allow范围内的命令静默执行。你在settings.json里怎么配直接决定它是靠谱助手还是危险分子。3.3 cc switch接入 DeepSeek / Qwen / GLM 等第三方模型很多人问 Claude Code 能不能用 DeepSeek、Qwen、GLM 这些模型。原生上 Claude Code 是 Anthropic 官方 CLI走的是 Anthropic API 兼容协议但协议本身是公开的社区很快就造出了 cc-switch 这个工具专门干切换 provider 这件事。# 安装 cc-switch 管理工具 npm install -g cc-switch # 启动图形化切换界面 cc-switch装好后在界面上新增一个 provider核心填三样东西API Base URL、API Key、模型映射名。以 DeepSeek 为例# 手动配置 DeepSeek 的 Anthropic 兼容端点 export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEYsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat # 启动 Claude Code claude参数说明ANTHROPIC_BASE_URL必须是对方服务商提供的 Anthropic 兼容端点路径写错直接 404最常见的错误是把 OpenAI 兼容端点填了进来。ANTHROPIC_MODEL填服务商映射后的模型名不是 Claude 的claude-sonnet-4-5这类名字。切换模型后务必/clear一次清掉旧模型上下文否则新模型接着旧模型的上下文接话经常答非所问。cc-switch 的本质就是把上面这些环境变量写进配置文件点一下按钮帮你切换省去手动 export 的麻烦。用不用它都行理解环境变量才是关键。4. 组合玩法VS Code 插件接线、LM Studio 本地模型与多模型切换4.1 VS Code 扩展从终端到 IDE 的桥接Claude Code 的入口在终端但真正改代码的时候很多人更习惯在 IDE 里看 diff。VS Code 扩展把终端的会话面板搬进了编辑器侧边栏安装后在任意项目里打开侧边栏会多出一个会话面板底层走的还是同一个 CLI 进程。它能读取当前打开的文件作为上下文修改后产生的 diff 直接显示在编辑器里比在终端里翻输出直观得多。这里有个参数值得注意VS Code 扩展默认继承你在终端里登录过的会话不需要重复登录。但如果你用 cc-switch 切了模型扩展需要重启一次才能加载新配置否则面板里用的还是旧模型的会话。遇到过好几次这个问题表现是扩展里问它 你现在是什么模型回答的还是上一家的名字——这就是没重启的典型症状。4.2 调用 LM Studio 本地模型本地模型的诉求通常是隐私和离线。LM Studio 是目前比较顺手的本地推理工具启动本地服务后默认监听http://localhost:1234协议上兼容 OpenAI 格式但 Claude Code 要的是 Anthropic 协议。好在 LM Studio 新版本的服务端同时支持 Anthropic API 兼容层只需要把环境变量指过去就行。# 在启动 Claude Code 前指定本地服务地址 export ANTHROPIC_BASE_URLhttp://localhost:1234 export ANTHROPIC_AUTH_TOKENlm-studio export ANTHROPIC_MODELqwen3-coder-32b-instruct # 启动 claude参数说明ANTHROPIC_AUTH_TOKEN填什么内容不重要LM Studio 本地服务不校验 key但 Claude Code 这个字段不能留空随便给个非空字符串就行。ANTHROPIC_MODEL填 LM Studio 里已加载的模型名大小写要和模型列表里完全一致填错会直接报模型找不到。本地模型的流畅度取决于显存和量化等级q4_k_m量化的 32B 模型在 24GB 显存上勉强能跑生成速度比云端慢一个数量级。指望本地模型有跟云端一样的响应速度不现实。用本地模型的代价是推理变慢、模型能力打折扣。我一般只在涉及敏感代码或网络受限的环境下用本地模型日常开发还是走云端的 Claude 模型速度和代码能力差距明显。4.3 多模型切换按任务类型选模型实际开发中不同任务适合不同模型我会在 cc-switch 里配三个档位来回切日常重构、写测试、改 bug用云端的 Claude Sonnet速度快代码质量稳。深度架构分析、长上下文梳理切到更强的大杯模型牺牲一点速度换理解深度。敏感代码审查、离线环境切到本地模型数据不出机器。用 cc-switch 在三个 provider 之间切换不需要记任何环境变量。切换后记得/clear重置会话再开始新任务。5. 避坑记录Claude Code 五个高频安装与运行事故现场5.1 Node 版本过低导致 npm 引擎检查失败现象Ubuntu 上执行npm install -g anthropic-ai/claude-code输出一大段警告然后安装失败核心提示是EBADENGINE。原因系统自带 Node 版本只有 10.x 或 12.x不满足 Claude Code 要求的 Node 18npm 引擎检查强制拦截。解决先用 nvm 切到 Node 20 LTS 再装nvm install 20 nvm use 20 node -v # 确认版本已经是 v20.x npm install -g anthropic-ai/claude-code5.2 登录时提示 Your organization has disabled claude subscription access for Claude Code现象claude login显示登录成功但进入会话时弹窗报Your organization has disabled claude subscription access for Claude Code根本进不去。原因账号是企业订阅管理员在组织策略里关掉了 CLI 工具的使用权限或者账号绑定的是工作区订阅而不是个人版订阅。解决确认你的订阅类型。个人订阅可以直接用 CLI企业订阅需要找组织管理员在后台把 Claude Code 权限打开。这个错误不是本地配置问题折腾 settings.json、重装 CLI 都没用问题在账号侧。5.3 Ubuntu 里装完却找不到 claude 命令现象npm 安装一路绿灯但新开一个终端敲claude提示 command not found。原因npm 的全局 bin 目录不在系统 PATH 里。npm config get prefix查出来的路径没有加到 shell 配置里。解决把 npm 全局 bin 目录追加到 PATHecho export PATH$PATH:$(npm config get prefix)/bin ~/.bashrc source ~/.bashrc which claude # 确认路径已生效5.4 终端命令执行被拒权限规则没有按预期放开现象在settings.json里明明allow了Bash(npm run test)但 Claude 执行测试时还是每次弹窗询问。原因权限匹配是精确匹配。Claude 实际执行的命令是Bash(npm run test -- --coverage)跟规则里的Bash(npm run test)不是同一条字符串规则就没匹配上。解决把 allow 规则改成前缀匹配模式放宽到命令族{ permissions: { allow: [Bash(npm run *)], deny: [Bash(rm:*), Bash(sudo:*)] } }5.5 VS Code 扩展连不上终端里已登录的 CLI现象终端里登录正常但 VS Code 扩展打开面板一直转圈报无法建立会话。原因VS Code 扩展以独立进程方式拉起 CLI没有继承终端里的登录态和环境变量。如果还用 cc-switch 切过 provider两边配置不一致的情况会更明显。解决杀掉 VS Code 里残留的 claude 进程重启窗口确认项目级和全局的settings.json配置一致用 cc-switch 切过 provider 的重启 VS Code 让扩展重新加载配置。6. 进阶技巧把手册源码拆成一套自动化的 slash command 工作流最后分享一个能实实在在提升效率的做法给自己配一套自定义斜杠命令。Claude Code 支持项目级自定义命令在.claude/commands/目录下放一个 Markdown 文件文件名就是命令名文件内容是提示词模板。以后在会话里敲/命令名就能一键触发不需要每次重新打字描述任务。--- description: 对当前 Git 改动做逐文件审查 argument-hint: [可选的提交范围] --- 请对当前分支相对 main 的改动执行以下审查 1. 逐个文件阅读 diff重点关注空指针、资源未释放、SQL 注入 2. 对每个问题标出文件路径、行号、严重级别 3. 如果问题有确定的修复方式直接给出补丁把这段内容保存为.claude/commands/review.md以后每次提交代码前在会话里敲/reviewClaude 就会按这套流程自动过一遍 diff。我还会配一个/preflight命令让它跑完测试后主动检查 TODO、FIXME 注释再确认打包命令能过再配一个/onboard进入陌生项目时自动列出目录结构、读配置文件、整理出一份项目理解笔记。整套工作流跑起来是这样的新项目进来先/onboard建立认知开发过程中直接对话改代码提交前/preflight强制自检合并前/review看 diff。每一步的产出都会沉淀成项目文档下次会话不用从头解释。从那以后我进一个陌生代码库的第一反应不是找 README而是先看有没有 CLAUDE.md没有就/init生成一份。这套习惯帮我省掉了很多重复解释项目的口水希望帮到你。本文还有配套的精品资源点击获取