## 概述 本教程面向从未接触过 Claude Code 的零基础读者，目标是用一个晚上把命令行里的 AI 编程助手彻底跑通，并亲手造出第一个能运行的小项目——一个**命令行名片生成器**（输入姓名、职位、联系方式，输出 ASCII 艺术名片并保存为文件）。学完你将掌握：环境准备、官方安装与国内代理两种装法、首次登录鉴权、`settings.json` 权限白名单配置、项目目录与 `CLAUDE.md` 立规矩，以及与 Claude Code 的标准提问循环。 ## 前置条件 - 一台 Windows 10/11、macOS 或主流 Linux 发行版电脑 - 终端基础：会 `cd` 切换目录、会新建文件夹即可，不要求会写代码 - 一个可联网的浏览器（首次登录要用） - 任选其一的鉴权方式：Anthropic 官方账号（订阅制 Claude Pro/Max，或按量付费 API Key），或第三方兼容端点 - Node.js 18 及以上（仅 npm 装法需要；原生装法可跳过） ## 第一步：搞清楚你正在装什么 Claude Code 不是网页版聊天框，而是一个**跑在终端里的智能体（Agent）**。它能读你电脑里的文件、改代码、执行命令、跑测试，再把结果反馈给模型继续推理。这意味着它的能力远超普通问答，但也意味着**权限管理**是入门第一课——它真的会按回车执行命令。 理解这一点后，安装只是把"可执行入口"放到 PATH 里；真正决定体验的是**鉴权方式**和**权限白名单**。后面的步骤都围绕这两件事展开。 ## 第二步：准备运行环境 如果你打算用 npm 方式安装，先确认 Node.js 版本： ```bash node --version # 期望输出 v18.x 或更高，例如 v20.18.0 ``` 若提示 `command not found` 或版本低于 18，去 Node.js 官网下载 LTS 版安装包，或用版本管理器： ```bash # macOS / Linux（推荐 nvm） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install --lts # Windows 推荐用 fnm 或直接装官方安装包 ``` 同时确认 Git 已就绪（Claude Code 会用它读项目历史）： ```bash git --version ``` **预期结果**：三条命令都有正常版本号输出。 **常见问题**：装完 Node 仍提示找不到命令——多半是 PATH 没刷新，**新开一个终端窗口**再试；Windows 下建议用 PowerShell 而非 cmd。 ## 第三步：两种安装方式，按场景选 ### 方式 A：npm 全局安装（最通用） ```bash npm install -g @anthropic-ai/claude-code ``` 装完验证： ```bash claude --version ``` ### 方式 B：原生安装（推荐，少踩坑） 原生安装不依赖 Node 版本、不会被全局包管理冲突拖累，适合长期使用： ```bash # macOS / Linux / WSL curl -fsSL https://claude.ai/install.sh | bash # Windows（PowerShell） irm https://claude.ai/install.ps1 | iex ``` **预期结果**：`claude` 命令在任何目录都能调用，`claude --version` 输出形如 `2.x.x` 的版本号。 **两种方式对比**： | 维度 | npm 安装 | 原生安装 | |------|---------|---------| | 依赖 | 需 Node 18+ | 无外部依赖 | | 升级 | `npm update -g` | `claude update` | | 适用 | 已有 Node 技术栈 | 所有用户首选 | **常见问题**：报 `EACCES` 权限错误——不要用 `sudo` 强装，改用 npm 前缀指向用户目录，或直接换原生安装。 ## 第四步：首次登录鉴权 在任意目录敲下： ```bash claude ``` 首次启动会进入交互界面并提示登录。按回车后，浏览器自动打开 OAuth 页面，登录你的 Anthropic 账号即可。终端会自动检测到登录成功。 如果你用**按量付费 API Key**（而非订阅），改用环境变量： ```bash # macOS / Linux export ANTHROPIC_API_KEY="sk-ant-xxxxxx" # Windows PowerShell $env:ANTHROPIC_API_KEY="sk-ant-xxxxxx" ``` 写进 `~/.zshrc` 或 `~/.bashrc` 可永久生效（注意别提交到 git）。 **国内用户走第三方端点**：国内直连官方常超时，可设兼容端点： ```bash export ANTHROPIC_BASE_URL="https://你的代理域名" export ANTHROPIC_API_KEY="代理商给你的key" ``` **预期结果**：终端出现输入提示符 `>`，能正常对话即鉴权成功。 **常见问题**：浏览器没自动弹出——复制终端里那串 URL 手动粘贴；提示鉴权失败——检查 Key 是否复制完整、是否带前后空格、订阅套餐是否到期。 ## 第五步：配置权限白名单（立第一道围栏） Claude Code 默认对危险操作会先征求你同意（弹出 `[y/n]`）。频繁确认很烦，但全放行又危险。正确做法是把**确定的只读命令**加进白名单。 进入交互界面后输入斜杠命令： ``` /permissions ``` 或直接编辑 `~/.claude/settings.json`： ```json { "permissions": { "allow": [ "Bash(node *)", "Bash(npm run *)", "Bash(git status)", "Bash(git diff *)", "Read(*)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push *)" ] } } ``` **预期结果**：白名单内的命令直接执行不再询问；`deny` 内的命令被硬拦截。 **常见问题**：改了 `settings.json` 不生效——JSON 格式错误（少了逗号或引号），用 `claude config list` 检查是否被正确加载。 ## 第六步：建立第一个项目并立规矩 新建项目目录并进入： ```bash mkdir ~/card-maker cd ~/card-maker git init ``` 在项目根目录放一个 `CLAUDE.md`，这是 Claude Code 每次启动都会自动读的"项目说明书"，用来约束它的行为： ```markdown # 名片生成器项目 ## 技术栈 - Node.js 18+，单文件 index.js，不引入框架 ## 约定 - 所有输出为 UTF-8 中文 - 文件保存到 ./output/ 目录，不存在则自动创建 - 不要自动 git commit，改完代码只跑一次自测 ## 测试命令 node index.js ``` **预期结果**：之后每次在该目录 `claude` 启动，模型都会先读到这份规矩，少跑偏。 ## 第七步：用 Claude Code 造名片生成器 在项目目录启动： ```bash claude ``` 然后输入一句需求（这是和 Claude Code 协作的核心动作——**用自然语言描述需求，让它写、它改、它测**）： > 帮我写一个命令行名片生成器 index.js：用 readline 交互式询问姓名、职位、手机、邮箱、一句话签名，然后用 ASCII 边框把信息排版成一张名片打印到终端，同时保存到 ./output/card.txt。完成后用 node index.js 跑一次自测。 Claude Code 会自动创建 `index.js`、写代码、运行、看输出、修 bug。你只需在它请求执行 `node index.js` 时按 `y` 同意。 它产出的 `index.js` 大致如下（这正是你的第一个可运行项目）： ```javascript const readline = require('readline'); const fs = require('fs'); const path = require('path'); function ask(rl, q) { return new Promise(res => rl.question(q, res)); } (async () => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); const name = (await ask(rl, '姓名：')).trim(); const title = (await ask(rl, '职位：')).trim(); const phone = (await ask(rl, '手机：')).trim(); const email = (await ask(rl, '邮箱：')).trim(); const sign = (await ask(rl, '签名：')).trim(); rl.close(); const lines = [ `姓名：${name}`, `职位：${title}`, `手机：${phone}`, `邮箱：${email}`, `签名：${sign}`, ]; const width = Math.max(...lines.map(l => [...l].length)) + 4; const border = '╭' + '─'.repeat(width) + '╮'; const bottom = '╰' + '─'.repeat(width) + '╯'; let card = border + '\n'; for (const l of lines) { const pad = width - [...l].length; card += '│ ' + l + ' '.repeat(pad) + ' │\n'; } card += bottom; console.log('\n' + card); const outDir = path.join(__dirname, 'output'); fs.mkdirSync(outDir, { recursive: true }); fs.writeFileSync(path.join(outDir, 'card.txt'), card, 'utf-8'); console.log('已保存到 output/card.txt'); })(); ``` **预期结果**：运行后逐项输入信息，终端打印一张带圆角边框的 ASCII 名片，并生成 `output/card.txt`。 **常见问题**：中文字符导致边框错位——上面的代码用 `[...l].length` 按码点计算宽度，已规避此问题；若仍错位，说明某些全角字符宽度为 2，可让 Claude "用 wcwidth 逻辑重排"。 ## 实战案例：把名片升级成 HTML 版 第一次成功后，给 Claude 追加一句话，体验"增量协作"的威力： > 在 index.js 基础上新增 --html 参数，调用时除文本名片外，再生成一个带渐变背景、居中卡片的 output/card.html，双击即可在浏览器打开。 它会自动加参数解析、写 HTML 模板、跑通验证。你由此完整经历了一个真实项目从 0 到 1、再从 1 到 2 的开发闭环——这正是 Claude Code 的日常用法。 ## 整体工作流程 ```mermaid flowchart TD A[准备 Node.js 18+ 与 Git] --> B{选择安装方式} B -->|原生安装| C1[curl/irm 一键脚本] B -->|npm 安装| C2[npm i -g @anthropic-ai/claude-code] C1 --> D[claude 首次启动] C2 --> D D --> E[浏览器 OAuth 登录 / 配 API Key] E --> F[编辑 settings.json 权限白名单] F --> G[mkdir 项目 + 写 CLAUDE.md 立规矩] G --> H[claude 启动并用自然语言提需求] H --> I[模型写代码/跑命令/看输出/自修] I --> J{自测通过?} J -->|否| I J -->|是| K[第一个项目完成] ``` ## 延伸阅读 - **官方文档**：`docs.anthropic.com/en/docs/claude-code` —— 权威命令参考与最佳实践 - **GitHub 仓库**：`github.com/anthropics/claude-code` —— 更新日志与已知问题 - **斜杠命令体系**：在交互界面输入 `/help` 查看全部内置命令，重点掌握 `/clear`、`/compact`、`/init` - **进阶方向**：学会本课后，可继续探索 Skills 自定义技能、MCP 工具扩展、`-p` 无头批量模式 ## 训练营适用性评估 - **适合类型**：AI 编程零基础训练营、企业内部提效赋能营、大学生入门工作坊 - **预计教学时长**：2 小时讲解 + 1 小时动手实验，共半天 - **难度评级**：★☆☆☆☆（纯入门） - **考核方式**：学员独立完成名片生成器并通过 `node index.js` 自测，输出 `card.txt` 与 `card.html` 两个产物即视为通关 ## 参考来源 1. [Claude Code 安装配置完整指南：Windows/Mac/Linux 全平台 + 国内 API 配置](https://zhuanlan.zhihu.com/p/2013750250721014697) — 全平台安装与国内代理端点配置 2. [Claude Code 完全指南：从入门到精通的全面教程](https://zhuanlan.zhihu.com/p/2031489748343185542) — 从安装到自动化工作流的系统性梳理 3. [保姆级教程 Win11 下从零部署 Claude Code](https://blog.csdn.net/Little_Carter/article/details/155130127) — Windows 本地环境与 VSCode 全流程 4. [Claude Code 完整指南：下载→安装→配置→加载 Skills 全流程实战](https://cloud.tencent.com.cn/developer/article/2699162) — 三平台安装与认证配置 5. [Claude Code 从入门到精通：安装、配置、命令与高级技巧详解](https://www.cnblogs.com/wzzkaifa/p/19079594) — 命令清单与高级技巧参考 > [!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 等场景全覆盖。