首页 › tutorials › 装通Claude Code造首个命令行名片生成器

概述

本教程面向从未接触过 Claude Code 的零基础读者，目标是用一个晚上把命令行里的 AI 编程助手彻底跑通，并亲手造出第一个能运行的小项目——一个命令行名片生成器（输入姓名、职位、联系方式，输出 ASCII 艺术名片并保存为文件）。学完你将掌握：环境准备、官方安装与国内代理两种装法、首次登录鉴权、settings.json 权限白名单配置、项目目录与 CLAUDE.md 立规矩，以及与 Claude Code 的标准提问循环。

前置条件

第一步：搞清楚你正在装什么

Claude Code 不是网页版聊天框，而是一个跑在终端里的智能体（Agent）。它能读你电脑里的文件、改代码、执行命令、跑测试，再把结果反馈给模型继续推理。这意味着它的能力远超普通问答，但也意味着权限管理是入门第一课——它真的会按回车执行命令。

理解这一点后，安装只是把"可执行入口"放到 PATH 里；真正决定体验的是鉴权方式和权限白名单。后面的步骤都围绕这两件事展开。

第二步：准备运行环境

如果你打算用 npm 方式安装，先确认 Node.js 版本：

node --version
# 期望输出 v18.x 或更高，例如 v20.18.0

若提示 command not found 或版本低于 18，去 Node.js 官网下载 LTS 版安装包，或用版本管理器：

# 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 会用它读项目历史）：

git --version

预期结果：三条命令都有正常版本号输出。

常见问题：装完 Node 仍提示找不到命令——多半是 PATH 没刷新，新开一个终端窗口再试；Windows 下建议用 PowerShell 而非 cmd。

第三步：两种安装方式，按场景选

方式 A：npm 全局安装（最通用）

npm install -g @anthropic-ai/claude-code

装完验证：

claude --version

方式 B：原生安装（推荐，少踩坑）

原生安装不依赖 Node 版本、不会被全局包管理冲突拖累，适合长期使用：

# 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 前缀指向用户目录，或直接换原生安装。

第四步：首次登录鉴权

在任意目录敲下：

claude

首次启动会进入交互界面并提示登录。按回车后，浏览器自动打开 OAuth 页面，登录你的 Anthropic 账号即可。终端会自动检测到登录成功。

如果你用按量付费 API Key（而非订阅），改用环境变量：

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-xxxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-xxxxxx"

写进 ~/.zshrc 或 ~/.bashrc 可永久生效（注意别提交到 git）。

国内用户走第三方端点：国内直连官方常超时，可设兼容端点：

export ANTHROPIC_BASE_URL="https://你的代理域名"
export ANTHROPIC_API_KEY="代理商给你的key"

预期结果：终端出现输入提示符 >，能正常对话即鉴权成功。

常见问题：浏览器没自动弹出——复制终端里那串 URL 手动粘贴；提示鉴权失败——检查 Key 是否复制完整、是否带前后空格、订阅套餐是否到期。

第五步：配置权限白名单（立第一道围栏）

Claude Code 默认对危险操作会先征求你同意（弹出 [y/n]）。频繁确认很烦，但全放行又危险。正确做法是把确定的只读命令加进白名单。

进入交互界面后输入斜杠命令：

/permissions

或直接编辑 ~/.claude/settings.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 检查是否被正确加载。

第六步：建立第一个项目并立规矩

新建项目目录并进入：

mkdir ~/card-maker
cd ~/card-maker
git init

在项目根目录放一个 CLAUDE.md，这是 Claude Code 每次启动都会自动读的"项目说明书"，用来约束它的行为：

# 名片生成器项目

## 技术栈
- Node.js 18+，单文件 index.js，不引入框架

## 约定
- 所有输出为 UTF-8 中文
- 文件保存到 ./output/ 目录，不存在则自动创建
- 不要自动 git commit，改完代码只跑一次自测

## 测试命令
node index.js

预期结果：之后每次在该目录 claude 启动，模型都会先读到这份规矩，少跑偏。

第七步：用 Claude Code 造名片生成器

在项目目录启动：

claude

然后输入一句需求（这是和 Claude Code 协作的核心动作——用自然语言描述需求，让它写、它改、它测）：

帮我写一个命令行名片生成器 index.js：用 readline 交互式询问姓名、职位、手机、邮箱、一句话签名，然后用 ASCII 边框把信息排版成一张名片打印到终端，同时保存到 ./output/card.txt。完成后用 node index.js 跑一次自测。

Claude Code 会自动创建 index.js、写代码、运行、看输出、修 bug。你只需在它请求执行 node index.js 时按 y 同意。

它产出的 index.js 大致如下（这正是你的第一个可运行项目）：

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 的日常用法。

整体工作流程

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[第一个项目完成]

延伸阅读

训练营适用性评估

参考来源

  1. Claude Code 安装配置完整指南：Windows/Mac/Linux 全平台 + 国内 API 配置 — 全平台安装与国内代理端点配置
  2. Claude Code 完全指南：从入门到精通的全面教程 — 从安装到自动化工作流的系统性梳理
  3. 保姆级教程 Win11 下从零部署 Claude Code — Windows 本地环境与 VSCode 全流程
  4. Claude Code 完整指南：下载→安装→配置→加载 Skills 全流程实战 — 三平台安装与认证配置
  5. Claude Code 从入门到精通：安装、配置、命令与高级技巧详解 — 命令清单与高级技巧参考

[!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 等场景全覆盖。

51学通信知识星球海报-扫码加入

📎 本分类最新文章