<!-- title: 零基础装通Claude Code造首个博客站点 -->

## 概述

本教程面向**从未用过 Claude Code 的零基础开发者**，目标是用一个下午完成三件事：把 Claude Code 装通跑起来、配好让它在你的项目里"懂事"、并亲手让它帮你造出第一个真正能用的项目——一个**零依赖的 Markdown 静态博客生成器**。读完你能掌握安装、认证、CLAUDE.md 项目记忆、权限放行、以及"探索—规划—验证"这套与 AI 协作的核心提问法。

## 前置条件

- 一台 macOS / Linux / Windows 电脑，能打开终端
- 一个 **Claude 付费订阅**（Pro $20/月起即包含 Claude Code；也可用 API 按量计费）。免费版不含 Claude Code
- 可选：Node.js 18+（用 npm 装法时需要；用官方原生安装器则**不需要 Node**）
- 会用 `cd`、`ls` 这类基础命令即可，不要求会写代码——这正是 Claude Code 帮你写

## 第一步：把 Claude Code 装通

Claude Code 现在官方推荐用**原生安装器**，不再强依赖 Node.js，且会后台自动更新、由 Anthropic 签名。三条路线任选其一：

**① 原生安装器（推荐，零 Node 依赖）**

```bash
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```

装完后二进制在 `~/.local/bin/claude`。若终端提示 `command not found`，把该目录加入 PATH：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # 或 ~/.bashrc
source ~/.zshrc
```

**② npm 全局安装（已有 Node 环境的人）**

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

**③ Homebrew（仅 macOS，需手动 `brew upgrade` 保持新版）**

```bash
brew install claude-code
```

**验证安装**：

```bash
claude --version
```

能打印出版本号即装通。

> **预期结果**：终端回显类似 `2.x.x` 的版本号。
> **常见问题**：Windows 报 `The token '&&' is not a valid statement separator` —— 说明你在 CMD 里跑了 PowerShell 命令，换到 PowerShell 重试即可。

## 第二步：登录认证与首次启动

进入你的项目目录（哪怕是个空文件夹也行）并启动：

```bash
mkdir my-blog && cd my-blog
claude
```

首次启动会引导你登录。两种主流方式：

- **OAuth 浏览器登录**（Pro/Max 订阅用户首选）：回车后自动打开浏览器，授权后凭证存入 `~/.claude/`，CLI 与桌面版共用。
- **API Key**：在 [Anthropic Console](https://console.anthropic.com/) 建一个 key，按提示粘贴，按量计费。

登录成功后，先别急着下指令，让它**先认识你的项目**。在交互框里输入：

```
这是什么项目？请先读一遍当前目录，告诉我你看到的结构和你的理解。
```

这一步官方称为"orienting Claude"，能显著提升后续每一次回答的质量。**任何文件改动前，Claude Code 默认都会先征求你同意**——零基础者不必担心它乱删东西。

## 第三步：用 CLAUDE.md 让它"懂事" + 配好权限

### 3.1 生成项目记忆文件

在交互框里输入：

```
/init
```

Claude 会扫描项目并生成一份 `CLAUDE.md`，记录项目目标、技术栈、命令、约定。这是 Claude Code 的**长期记忆**——每次启动都会自动读它。你可以手动补充几行，让它更贴合你：

```markdown
# CLAUDE.md
- 项目：Markdown 静态博客生成器
- 技术栈：Node.js，零第三方依赖优先
- 构建命令：node build.mjs
- 输出目录：dist/（生成物，可随时删除重建）
- 约定：中文注释，函数名用英文
```

### 3.2 减少"逐条放行"的权限弹窗

默认每次跑命令都要你确认，初期安全但繁琐。用 `/config` 打开设置，或在项目根目录建 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(node build.mjs)",
      "Bash(npm install)",
      "Bash(ls:*)",
      "Read(*)"
    ]
  }
}
```

把**只读和构建类**安全命令放进白名单，危险操作（如 `rm`、`git push`）仍会拦下问你。这样既流畅又不失控。

## 第四步：让 Claude Code 造首个静态博客生成器

现在进入正题。我们要做一个真实可用的工具：读 `posts/` 下的 Markdown，转成带样式的 HTML，并生成一个列出所有文章的首页。

### 4.1 用对提问姿势（探索—规划—验证）

官方最佳实践反复强调一句话：**先探索，再规划，最后写代码；并且给 Claude 一个能自己跑的验证手段**。把这段话原样发给它：

```
帮我造一个零依赖的 Node.js 静态博客生成器 build.mjs：
1. 读 posts/ 下所有 .md 文件；
2. 把 Markdown 转成 HTML（覆盖 # ## 标题、段落、- 列表、**加粗**、`行内代码`、[链接](url)）；
3. 每篇生成 dist/<slug>.html，带统一 CSS 和"返回首页"链接；
4. 生成 dist/index.html，列出所有文章标题并链接；
5. 顺手建两篇示例 posts/hello.md 和 posts/second.md；
6. 写完运行 node build.mjs，确认 dist/ 下生成了 3 个 html（含 index），
   并把 index.html 前几行打印出来给我看。若报错就自己修到通过。
```

注意最后一句——"运行验证、报错就修"——这正是把验证闭环交给 AI 的关键，让它自己迭代到通过，而不是每错一次都等你。

### 4.2 预期产出

Claude 会创建如下结构：

```
my-blog/
├── CLAUDE.md
├── build.mjs          # 生成器主程序
└── posts/
    ├── hello.md
    └── second.md
```

核心 `build.mjs` 大致长这样（Claude 写出来的版本，零依赖）：

```js
// build.mjs — 零依赖静态博客生成器
import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
import { join } from 'node:path';

const POSTS_DIR = 'posts';
const OUT_DIR = 'dist';

// 行内规则：代码、加粗、链接
function inline(text) {
  return text
    .replace(/`([^`]+)`/g, '<code>$1</code>')
    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
}

// 极简 Markdown → HTML（标题 / 段落 / 列表）
function mdToHtml(md) {
  let html = '', inList = false;
  const close = () => { if (inList) { html += '</ul>\n'; inList = false; } };
  for (const raw of md.split('\n')) {
    const line = raw.trimEnd();
    if (/^##\s+/.test(line))      { close(); html += `<h2>${inline(line.replace(/^##\s+/, ''))}</h2>\n`; }
    else if (/^#\s+/.test(line))  { close(); html += `<h1>${inline(line.replace(/^#\s+/, ''))}</h1>\n`; }
    else if (/^[-*]\s+/.test(line)){ if (!inList){ html+='<ul>\n'; inList=true; } html += `  <li>${inline(line.replace(/^[-*]\s+/, ''))}</li>\n`; }
    else if (line.trim() === '')  { close(); }
    else                          { close(); html += `<p>${inline(line)}</p>\n`; }
  }
  close();
  return html;
}

const CSS = `body{font-family:system-ui,sans-serif;max-width:720px;margin:40px auto;padding:0 20px;line-height:1.7;color:#222}
h1{border-bottom:2px solid #eee;padding-bottom:8px} a{color:#2563eb}
code{background:#f4f4f4;padding:2px 6px;border-radius:4px} .post{padding:12px 0;border-bottom:1px solid #eee}`;

const page = (title, body) => `<!doctype html><html lang="zh"><head><meta charset="utf-8">
<title>${title}</title><style>${CSS}</style></head><body>${body}</body></html>`;

const titleOf = (md, fb) => (md.match(/^#\s+(.+)$/m) || [, fb])[1];
const slugOf  = (n) => n.toLowerCase().replace(/[^\w\u4e00-\u9fa5]+/g, '-').replace(/^-|-$/g, '');

await mkdir(OUT_DIR, { recursive: true });
const files = (await readdir(POSTS_DIR)).filter(f => f.endsWith('.md'));
const index = [];

for (const file of files) {
  const md = await readFile(join(POSTS_DIR, file), 'utf8');
  const title = titleOf(md, file.replace(/\.md$/, ''));
  const slug = slugOf(title) || file.replace(/\.md$/, '');
  const body = `<h1>${title}</h1>\n${mdToHtml(md)}\n<p><a href="index.html">← 返回首页</a></p>`;
  await writeFile(join(OUT_DIR, `${slug}.html`), page(title, body));
  index.push({ title, slug });
}

const list = index.map(p => `<div class="post"><a href="${p.slug}.html">${p.title}</a></div>`).join('\n');
await writeFile(join(OUT_DIR, 'index.html'), page('我的博客', `<h1>我的博客</h1>\n${list}`));
console.log(`✅ 生成 ${index.length} 篇文章 → ${OUT_DIR}/`);
```

### 4.3 运行与验证

```bash
node build.mjs
# ✅ 生成 2 篇文章 → dist/
```

浏览器打开 `dist/index.html`，应看到两篇文章标题，点进去是带样式的正文。零依赖、零编译、双击即看。

### 4.4 进阶：换上专业 Markdown 引擎

当基础版跑通后，让 Claude 升级——只改一行：

```
把 mdToHtml 换成用 marked 库解析（npm install marked），其余逻辑不变，跑通验证。
```

Claude 会执行 `npm install marked`，把转换逻辑替换为 `import { marked } from 'marked'; marked.parse(md)`，并再次自检通过。这就是 Claude Code 的典型迭代节奏：**先跑通最小版本，再小步升级**。

## 常见问题与解决方案

| 现象 | 原因 | 解决 |
|---|---|---|
| `claude: command not found` | PATH 未含安装目录 | `export PATH="$HOME/.local/bin:$PATH"` 并写入 shell 配置 |
| 登录后仍提示未授权 | 凭证过期或换号 | 交互框内 `/login` 重新认证 |
| 国内网络连不上 | 需代理 | 设 `HTTPS_PROXY` 环境变量后再启动 |
| 每条命令都要确认 | 权限白名单未配 | 按第三步配置 `.claude/settings.json` 的 `allow` |
| 跑着跑着变"健忘" | 上下文窗口塞满 | `/compact` 压缩历史，或 `/clear` 重开并保留 CLAUDE.md |
| 生成结果不符合预期 | 提问太泛 | 补具体约束 + 让它先复述计划（`/plan` 模式）|

## 实战案例延伸

博客跑通后，可以用同样套路继续扩展，每一个都是给 Claude 的好练习：

1. **加文章元信息**：在 Markdown 顶部用 `<!-- date: 2026-07-05 -->` 标日期，首页按日期倒序排列。
2. **加标签页**：解析 `#标签`，生成 `dist/tags.html` 按标签归类。
3. **监听自动重建**：用 `chokidar` 或 Node 原生 `fs.watch`，文件一改就重新生成。
4. **部署上线**：让 Claude 帮你把 `dist/` 推到 GitHub Pages 或 Cloudflare Pages。

每一步都遵循同一节奏：**说清目标 → 给验证手段 → 让它自检迭代 → 你只看结果**。

## 整体工作流程

```text
flowchart TD
    A[安装 Claude Code<br/>原生/npm/brew] --> B[claude 启动并登录]
    B --> C[让 Claude 先读项目<br/>建立认知]
    C --> D[/init 生成 CLAUDE.md<br/>写清项目记忆]
    D --> E[配置 .claude/settings.json<br/>放行安全命令]
    E --> F[下达任务：探索→规划→验证]
    F --> G[Claude 写 build.mjs + 示例文章]
    G --> H[自动运行 node build.mjs 自检]
    H --> I{dist/ 生成正确?}
    I -- 否 --> F
    I -- 是 --> J[浏览器打开 index.html 验收]
    J --> K[小步升级：marked/标签/部署]
```

## 延伸阅读

- [Claude Code 官方最佳实践](https://code.claude.com/docs/en/best-practices) — 探索-规划-验证、上下文管理、子代理等核心方法论
- [Claude Code 官方快速开始](https://code.claude.com/docs/en/quickstart) — 安装、认证、首条命令的官方版
- [CLI 命令参考](https://code.claude.com/docs/en/cli-reference) — 全部命令与 flag 速查
- [Claude Code 安装与上手完整指南（neurohive, 2026）](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — 含桌面版、定价、CLAUDE.md 详解
- [40+ Claude Code Tips（ykdojo）](https://github.com/ykdojo/claude-code-tips) — 从基础到进阶的社区技巧合集

## 训练营适用性评估

- **适合训练营类型**：AI 编程入门营、前端/全栈零基础营、个人开发者工具营。本教程是任何"Claude Code 系列"的**第一课**，为后续 Skills、MCP、自动化等进阶主题打底。
- **预计教学时长**：**2.5–3 小时**。其中安装认证 30 分钟、CLAUDE.md 与权限配置 30 分钟、博客生成器实战 90–120 分钟（含答疑）。
- **教学形式建议**：前半段讲师演示 + 学员跟做，后半段学员自行扩展（加标签/排序），讲师巡场答疑。结营交付物：每人一个可部署的个人静态博客。
- **前置门槛**：低。会用终端即可，不要求会写 JavaScript——这正是让 AI 帮你跨过"不会写代码"这道坎的最佳入门项目。

## 参考来源

1. [Best practices for Claude Code — 官方文档](https://code.claude.com/docs/en/best-practices) — 探索-规划-验证、上下文窗口管理、给 Claude 验证手段等核心方法论
2. [Claude Code: Complete Guide to Installation and Getting Started (2026) — neurohive](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — 三种安装方式、定价、首次运行、CLAUDE.md 与核心命令
3. [CLI reference — Claude Code Docs](https://code.claude.com/docs/en/cli-reference) — 命令与 flag 完整参考
4. [40+ Claude Code Tips: From Basics to Advanced — GitHub ykdojo](https://github.com/ykdojo/claude-code-tips) — 社区整理的从基础到进阶技巧
5. [Claude Code Cheat Sheet [2026] — ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 默认模型、斜杠命令、CLI flag 速查表

> [!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学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)