# 三端打通 Claude Code 入门：终端 + IDE + Web 联动配置全流程 ## 概述 本教程面向**第一次接触 Claude Code 的开发者**，目标是用一节课的时间打通 Claude Code 的三个工作面：**终端 CLI、IDE 插件（VS Code/JetBrains）、Web 端（claude.ai/code）**。学完你将掌握：在一台机器上完成安装与认证、搭好"配置三层"（settings.json / 权限 / CLAUDE.md）、让三个界面共享同一份配置与会话，并用一个真实可运行的小项目——**Git 历史日报生成器**——跑通完整闭环。适合零基础、但希望一开始就建立"工程化配置习惯"的人。 ## 前置条件 - 一台 macOS / Windows / Linux 电脑，能联网 - **Node.js 18 及以上**（终端 CLI 走 npm 安装时需要） - 一个 **Anthropic 账号**（可用 Claude 订阅或 API Key 登录） - 已安装 **VS Code**（用于演示 IDE 插件联动；JetBrains 系同理） - 一个终端模拟器（macOS 自带 Terminal/iTerm，Windows 推荐 WSL 或 PowerShell，Linux 任意） - 不需要先懂 Git 进阶命令，但最好有一个带几次提交的本地 Git 仓库用于最后的实战案例 --- ## 正文：六步打通三端 ### 第 1 步：先认清 Claude Code 的"三个工作面" 很多人以为 Claude Code 只是"一个命令行工具"，这是最大的认知偏差。到 2026 年，它已经是一套**多前端、单内核**的产品。内核是同一个 Agent 引擎，前端有三个入口： | 工作面 | 形态 | 典型场景 | |--------|------|----------| | **终端 CLI** | `claude` 命令 | 脚本化、CI/CD、服务器、SSH 远程 | | **IDE 插件** | VS Code / JetBrains 扩展 | 日常写代码、看 diff、跳转 | | **Web 端** | claude.ai/code | 浏览器里直接开环境、跨设备接力 | 关键认知：**三端共享同一套配置文件、同一套权限规则、同一个登录态**。你在终端里写好的 `CLAUDE.md` 和 `settings.json`，VS Code 插件会自动读取；Web 端连接到本地环境后也沿用同一份。理解这一点，后面所有的配置动作才不会重复造轮子。 > **常见问题**：三端要分别装、分别登录吗？ > **解答**：终端 CLI 和 IDE 插件共用本机登录态，装一次登录一次即可；Web 端是独立的浏览器会话，但可通过"连接本地环境"复用你的项目。 ### 第 2 步：安装终端 CLI（核心入口） 打开终端，执行一条命令完成全局安装： ```bash npm install -g @anthropic-ai/claude-code ``` 安装完成后，验证版本： ```bash claude --version ``` **预期结果**：终端打印出形如 `2.x.x` 的版本号，表示 CLI 已就绪。 如果你所在网络对 npm 官方源较慢，可临时切换镜像，或使用官方提供的原生安装脚本（无需 Node.js）： ```bash # 原生安装（不依赖 npm，适合服务器/精简环境） curl -fsSL https://claude.ai/install.sh | bash ``` > **常见问题 1**：`npm: command not found` > **解答**：先安装 Node.js 18+（推荐用 nvm 管理），再重试。 > > **常见问题 2**：权限报错 `EACCES` > **解答**：不要用 `sudo`。推荐配置 npm 全局目录到用户家目录，或直接改用原生安装脚本。 > > **常见问题 3**：Windows 上 `claude` 命令找不到 > **解答**：确认 npm 全局 bin 目录在 `PATH` 中；或在 PowerShell 里用 `where.exe claude` 定位。 ### 第 3 步：首次认证与启动 进入任意目录（建议新建一个练习目录），启动： ```bash mkdir claude-lab && cd claude-lab claude ``` 首次启动会要求登录。两种方式二选一： 1. **浏览器 OAuth 登录**（推荐）：终端给出一个链接，浏览器打开后授权，回终端即登录成功。 2. **API Key 方式**：设置环境变量后启动，适合无图形界面的服务器。 ```bash # API Key 方式（无头环境） export ANTHROPIC_API_KEY="sk-ant-xxxxxx" claude ``` 启动后进入**交互式 REPL**，提示符变为 `>`。先认识几个"保命命令"： ``` /help # 查看所有命令 /config # 打开图形化设置面板（标签式） /init # 让 Claude 扫描当前项目并生成 CLAUDE.md /clear # 清空当前会话上下文 /compact # 压缩上下文（长会话省钱利器） /cost # 查看本次会话 token 消耗 /model # 切换模型 ``` **预期结果**：在 REPL 里输入一句"介绍一下你自己能做什么"，能正常得到回复，说明认证与会话链路全通。 > **常见问题**：登录后仍提示未授权 > **解答**：检查系统时间是否正常（OAuth 对时间敏感）；企业网络代理可能拦截回调，尝试切换网络或配置 `HTTPS_PROXY`。 ### 第 4 步：搭好"配置三层"——Claude Code 的灵魂 这一步是把 Claude Code 从"玩具"变成"工程化工具"的关键。配置分三层，**优先级从高到低**： 1. **用户级** `~/.claude/settings.json`——所有项目通用的全局偏好 2. **项目级（共享）** `<项目>/.claude/settings.json`——随仓库提交、团队共享 3. **项目级（本地）** `<项目>/.claude/settings.local.json`——个人私有，应加入 `.gitignore` 加上两个"记忆体"： - **`CLAUDE.md`**——自然语言写成的项目说明书，放在项目根目录，Claude 每次启动自动读取 - **会话内 `#` 快速记忆**——输入以 `#` 开头的一句话，会被写入记忆 下面给一份**可直接复用的最小配置**。先用 `/config` 面板看一眼，再手动编辑文件更可控。 `<项目>/.claude/settings.json`（团队共享，提交到 Git）： ```json { "permissions": { "allow": [ "Bash(git log:*)", "Bash(git diff:*)", "Bash(git status:*)", "Bash(npm test:*)", "Read(**)", "Edit(src/**)" ], "ask": [ "Bash(git push:*)", "Bash(npm install:*)" ], "deny": [ "Bash(rm -rf *)", "Read(.env)", "Read(**/*.key)" ] } } ``` `<项目>/.claude/settings.local.json`（个人私有，不提交）： ```json { "permissions": { "allow": ["Bash(open:*)", "Bash(code:*)"] } } ``` 权限语义解读： - `allow`：命中即**自动放行**，不再弹确认 - `ask`：命中即**弹确认**，你来决定 - `deny`：命中即**硬拒绝**，连问都不问 权限语法是 `工具名(匹配规则)`，支持通配符 `*`。例如 `Bash(git log:*)` 表示允许任何 `git log` 开头的命令；`Read(.env)` 表示禁止读取 `.env`。 **权限模式（permissionMode）**四档，可在 `settings.json` 或运行时指定： | 模式 | 行为 | 适用 | |------|------|------| | `default` | 命中 allow 放行，其余询问 | 日常开发 | | `acceptEdits` | 自动接受文件编辑 | 批量重构 | | `plan` | 只规划不执行 | 方案评审 | | `bypassPermissions` | 全部放行（危险） | 仅信任的沙箱 | > **常见问题**：每次都弹一堆确认，烦死了 > **解答**：把高频只读/安全命令加进 `allow`；把危险命令加进 `deny`。目标是把"确认疲劳"降到接近零，又不裸奔。 再写一个最小 `CLAUDE.md`（项目根目录）： ```markdown # 项目说明 本项目是练习 Claude Code 三端联动的沙箱。 ## 约定 - 所有脚本放在 `scripts/` 目录 - 输出报告统一写为 Markdown，放 `reports/` - 命令必须幂等，重复运行不报错 - 不要提交 .env 和 *.key ``` 执行 `/init` 可让 Claude 自动扫描代码库生成一份更完整的 `CLAUDE.md`，再手动微调即可。 ### 第 5 步：装 IDE 插件并联动 打开 VS Code，进入扩展商店，搜索 **"Claude Code"**（Anthropic 官方），安装。 安装后两种唤起方式： - **快捷键**：`Ctrl+Esc`（macOS 为 `Cmd+Esc`）从编辑器内唤出 Claude 面板 - **命令面板**：`Ctrl+Shift+P` 输入 `Claude Code: Open` **预期结果**：面板内出现与终端一致的交互界面，且自动读取了第 4 步写好的 `settings.json` 与 `CLAUDE.md`——无需重新配置。选中编辑器里的一段代码，让 Claude"解释这段代码"或"加注释"，它会带着当前文件上下文作答。 > **常见问题 1**：插件提示找不到 `claude` 命令 > **解答**：插件依赖本机已安装的 CLI。确认 `claude --version` 在终端能跑通，且 PATH 对 GUI 应用可见（macOS GUI 应用的 PATH 可能与终端不同，重启 VS Code 通常解决）。 > > **常见问题 2**：插件和终端的会话是同一个吗？ > **解答**：不是同一个会话实例，但**共享配置**。你可以在终端开长任务、在 IDE 里做小修改，互不干扰。 ### 第 6 步：用 claude.ai/code Web 端接力 浏览器访问 **claude.ai/code**，登录同一账号。Web 端的价值在于"跨设备接力"和"零安装体验"：你可以在公司电脑的 VS Code 里改了一半的代码，回家用浏览器打开 Web 端继续。 让 Web 端连到你本地项目的典型路径：在 VS Code 插件或 CLI 中触发"连接到 claude.ai"，浏览器扫码确认后，Web 端即可看到该会话。 **预期结果**：Web 端能看到本地会话历史，配置与权限规则与本机一致。 > **常见问题**：Web 端能直接改我电脑上的文件吗？ > **解答**：需要通过连接本地环境（CLI/插件作为桥梁）才可操作本机文件；纯 Web 沙箱环境则是隔离的云端空间。 --- ## 实战案例：Git 历史日报生成器 现在用一个完整项目串起三端。目标：**读取当前 Git 仓库的提交历史，自动生成一份 Markdown 每日开发报告**。这个项目天然适合 Claude Code——它需要读文件、跑命令、写报告，三端都能驱动。 ### 0. 准备仓库 ```bash mkdir git-daily && cd git-daily git init echo "# Git Daily Report" > README.md git add . && git commit -m "init: 项目初始化" # 再随便造几条提交 echo "v1" >> README.md && git commit -am "docs: 更新 README" ``` ### 1. 启动 Claude Code ```bash claude ``` ### 2. 一句话下需求 在 REPL 里输入（可直接复制）： ``` 请帮我写一个 Python 脚本 scripts/git_daily.py： 1. 调用 git log 获取"今天"的所有提交（按作者分组） 2. 统计每个作者的提交数、改动文件数 3. 输出为 reports/REPORT-<日期>.md，使用 Markdown 表格 4. 运行后自动用默认编辑器打开报告 要求幂等：reports 目录不存在时自动创建。 ``` ### 3. 预期产出 Claude 会创建 `scripts/git_daily.py`，内容大致如下（它会按你的 `CLAUDE.md` 约定放对目录）： ```python #!/usr/bin/env python3 """生成每日 Git 开发报告。幂等：目录不存在自动创建。""" import subprocess, datetime, os, pathlib REPO = pathlib.Path(__file__).resolve().parent.parent REPORTS = REPO / "reports" TODAY = datetime.date.today().isoformat() def run(cmd): return subprocess.run(cmd, cwd=REPO, capture_output=True, text=True).stdout def main(): REPORTS.mkdir(exist_ok=True) # 幂等 # 取今日提交：作者|提交hash|标题 raw = run(["git", "log", "--since=midnight", "--pretty=format:%an|%h|%s"]) from collections import defaultdict by_author = defaultdict(list) for line in raw.strip().splitlines(): if "|" in line: author, h, title = line.split("|", 2) by_author[author].append((h, title)) files = run(["git", "log", "--since=midnight", "--name-only", "--pretty=format:"]).split() lines = [f"# 每日开发报告 {TODAY}", "", f"- 提交作者数：{len(by_author)}", f"- 改动文件数：{len(set(files))}", "", "## 提交明细", "", "| 作者 | 提交数 | 提交列表 |", "|------|--------|----------|"] for author, commits in by_author.items(): titles = ", ".join(f"`{h}` {t}" for h, t in commits) lines.append(f"| {author} | {len(commits)} | {titles} |") out = REPORTS / f"REPORT-{TODAY}.md" out.write_text("\n".join(lines), encoding="utf-8") print(f"✅ 报告已生成：{out}") # 自动打开（macOS=open / Windows=默认 / Linux 可按需调整） opener = "open" if os.name != "nt" else os.startfile if os.name == "nt": os.startfile(out) else: subprocess.run([opener, str(out)]) if __name__ == "__main__": main() ``` ### 4. 运行验证 在终端执行： ```bash python3 scripts/git_daily.py ``` 因为你在 `settings.json` 里已经 `allow` 了 `Bash(git log:*)` 和 `Read(**)`，所以这一步不会反复弹确认。 ### 5. 三端接力演示 - **终端 CLI**：跑上面的命令，看报告生成。 - **VS Code 插件**：选中 `git_daily.py`，对 Claude 说"给这个脚本加类型注解和单元测试"，它会就地修改并在编辑器里高亮 diff。 - **Web 端**：连上本地后，在浏览器里继续说"把报告里加上'本周累计提交数'一列"，改完在终端复跑即可。 ### 6. 常见问题 - **报告为空**：仓库今日没有提交，`--since=midnight` 换成 `--since="1 week ago"` 验证脚本逻辑。 - **`git` 命令失败**：确认在仓库目录内运行，或确认 `git` 已加入 PATH。 - **中文乱码**：读写统一用 `encoding="utf-8"`（脚本已处理）。 --- ## 工作流程图：三端如何协同 ```mermaid flowchart TB subgraph 内核["Claude Code Agent 引擎（单一内核）"] ENGINE[配置解析 + 权限裁决 + 工具调用] end subgraph 配置层["配置三层（共享）"] S1["~/.claude/settings.json
用户全局"] S2[".claude/settings.json
项目共享"] S3[".claude/settings.local.json
个人私有"] MD["CLAUDE.md
项目记忆"] end CLI["终端 CLI
claude 命令"] --> ENGINE IDE["IDE 插件
VS Code / JetBrains"] --> ENGINE WEB["Web 端
claude.ai/code"] --> ENGINE S1 --> ENGINE S2 --> ENGINE S3 --> ENGINE MD --> ENGINE ENGINE -->|读文件/跑命令/写报告| FS[本机文件系统与 Git 仓库] style ENGINE fill:#fde68a,stroke:#b45309,stroke-width:2px style MD fill:#bbf7d0,stroke:#15803d ``` 核心结论：**前端换皮，内核不变，配置一份**。所以你的精力应花在配好 `settings.json` 和 `CLAUDE.md` 上，而不是在三端各配一遍。 --- ## 延伸阅读 - **官方 Quickstart**：`code.claude.com/docs/en/quickstart`——最快的上手起点 - **Settings 文档**：`code.claude.com/docs/en/settings`——所有配置项的权威说明 - **权限配置文档**：`code.claude.com/docs/en/permissions`——allow/ask/deny 规则细节 - **npm 包主页**：`npmjs.com/package/@anthropic-ai/claude-code`——版本与变更日志 - 后续可深入：Hooks（事件钩子）、Subagents（子代理）、MCP（外部工具接入）、`-p` 无头模式与 CI 集成 --- ## 训练营适用性评估 | 维度 | 说明 | |------|------| | **适合训练营类型** | 通用开发者入门营、前端/后端/DevOps 工程效能营、AI 辅助编程训练营 | | **难度** | ★★☆☆☆（零基础可上手，配置层需一点点耐心） | | **建议时长** | 讲授 45 分钟 + 动手实验 60 分钟，合计约 2 课时 | | **前置依赖** | 无（自带 Node.js 安装环节） | | **可考核产出** | 学员提交一个含 `settings.json` + `CLAUDE.md` + 可运行脚本的小仓库 | | **延伸作业** | 把日报生成器升级为"周报 + 月报"，并接入 GitHub Actions 定时运行（衔接后续 CI 章节） | | **不适合** | 纯非技术受众；对命令行完全抵触者建议先用 Web 端体验再回头装 CLI | --- ## 参考来源 1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方快速上手指南，安装与首条命令 2. [How to Install Claude Code: Complete Setup Guide (2026)](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — npm/原生安装与系统要求 3. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — settings.json 分层与环境变量权威说明 4. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — allow/ask/deny 权限规则与四种模式 5. [Getting Started with Claude Code in 2026: Setup to First Commit](https://septimlabs.com/blog/getting-started-with-claude-code-2026) — 从安装到首次提交的五步实战 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。