<!-- title: 零基础装通并造首个网页看板应用 -->

# Claude Code 入门篇：零基础装通并造首个网页看板

## 概述

本教程面向**完全零基础**的读者，带你从安装 Claude Code 到独立交付一个**可运行的交互式网页看板应用**（三列待办看板 + 本地存储）。学完后你将掌握：跨平台安装与认证、四类配置入口、权限模式切换、`/init` 项目记忆生成，以及如何用自然语言驱动 Claude Code 完成 HTML/CSS/JS 全栈小项目的开发与调试。全程只需敲十几条命令，不需要先学会写代码。

## 前置条件

- 一台 macOS、Windows 或 Linux 电脑，能联网
- **Node.js 18 及以上版本**（推荐 20 LTS，用于 npm 安装方式；原生安装器方式可不强依赖）
- 一个 Anthropic 账号（订阅 Claude Pro/Max 即可用账号登录），或一个 Anthropic API Key
- 一个终端：macOS/Linux 自带 Terminal；Windows 推荐 PowerShell 或 Git Bash
- 浏览器一枚（Chrome/Edge/Firefox 任选），用来预览网页成果

无需任何编程基础。Claude Code 会替你把自然语言翻译成可运行代码。

---

## 第一步：确认运行环境

Claude Code 是一个跑在终端里的命令行智能体（agentic CLI）。它依赖 Node.js 运行时（npm 安装路径）或官方原生安装器（不依赖 npm）。

打开终端，先检查 Node.js 是否就位：

```bash
node -v
npm -v
```

**预期结果**：返回类似 `v20.11.0` 和 `10.2.4` 的版本号。

**常见问题与解决**：

| 现象 | 原因 | 解决 |
|------|------|------|
| `command not found: node` | 未安装 Node.js | 访问 nodejs.org 下载 LTS 安装包，或用 nvm 安装 |
| 版本低于 18 | Node 版本过旧 | 升级到 18+，推荐用 nvm 管理多版本 |
| Windows 提示无法识别 `node` | 环境变量未生效 | 重启 PowerShell，或勾选安装时的"Add to PATH" |

如果你在国内网络环境，建议先配好 npm 国内镜像，避免下载缓慢：

```bash
npm config set registry https://registry.npmmirror.com
```

---

## 第二步：安装 Claude Code

Claude Code 现提供**两条主流安装路径**，二选一即可。

### 方式 A：官方原生安装器（推荐新手）

不依赖 npm，一条命令搞定，自动处理升级：

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

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

**预期结果**：终端滚动安装日志，最后提示 `Claude Code installed successfully`，并告诉你 `claude` 命令已加入 PATH。

### 方式 B：npm 全局安装

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

**预期结果**：安装完成后，执行 `claude --version` 能打印出版本号，例如 `2.x.x`。

**常见问题与解决**：

| 现象 | 原因 | 解决 |
|------|------|------|
| `EACCES: permission denied` | 全局安装无权限 | macOS/Linux 加 `sudo`，或改用 nvm 管理 Node（推荐，免 sudo） |
| 安装卡住不动 | 网络访问 npm 慢 | 切换国内镜像 `npmmirror`，或挂代理 |
| 装完提示 `claude: command not found` | PATH 未更新 | 重开终端；或手动把安装路径加入 PATH |
| Windows PowerShell 报执行策略错误 | 脚本执行被禁 | 以管理员运行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |

---

## 第三步：首次启动与认证

在任意目录敲下：

```bash
claude
```

首次运行会进入交互式向导，引导你完成登录。两种认证方式：

1. **账号登录（推荐订阅用户）**：终端打印一个网址，浏览器自动打开，确认授权后回终端即登录成功，无需手动管理 Key。
2. **API Key 登录**：到 console.anthropic.com 创建 Key，设置环境变量：

```bash
# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-xxxx"

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

**预期结果**：终端出现 `Welcome to Claude Code!` 欢迎语，光标停在输入提示符 `>` 处，说明已就绪。

> 国内用户若直连不稳定，可配置第三方兼容网关：设置 `ANTHROPIC_BASE_URL` 指向你的代理地址，Claude Code 会把请求转发过去。

**常见问题与解决**：

| 现象 | 原因 | 解决 |
|------|------|------|
| 浏览器打不开授权页 | 无图形环境/服务器 | 改用 API Key 方式登录 |
| `Invalid API key` | Key 复制错或过期 | 重新生成，注意去掉首尾空格 |
| 一直转圈超时 | 网络无法访问 Anthropic | 配置代理或兼容网关 |

---

## 第四步：认识四大配置入口

Claude Code 的配置分散在四个层级，理解它们你就掌握了"调教"它的全部开关：

| 入口 | 作用 | 何时用 |
|------|------|--------|
| `/config`（交互命令） | 切主题、改默认模型、调权限 | 临时调整个人偏好 |
| `settings.json`（文件） | 持久化权限、环境变量、钩子 | 团队/项目固化规则 |
| `CLAUDE.md`（项目记忆） | 告诉 Claude 项目背景、规范、约定 | 让它长期记住"这个项目怎么做" |
| 命令行参数 | 一次性覆盖（如 `--permission-mode`） | 跑自动化、CI |

先熟悉最常用的几个斜杠命令：

```text
/help          查看所有命令
/init          让 Claude 扫描项目并生成 CLAUDE.md
/model         切换模型（Sonnet / Opus / Haiku）
/config        打开设置面板
/cost          查看本次会话 token 花费
/clear         清空当前上下文重新开始
/compact       压缩上下文（对话太长时用）
```

在欢迎界面输入 `/help` 回车，应能看到完整命令清单。这就是你的"方向盘"。

---

## 第五步：创建项目并用 /init 生成记忆

选定一个工作目录，比如桌面：

```bash
mkdir ~/kanban-board && cd ~/kanban-board
claude
```

进入 Claude Code 后，第一条命令建议敲：

```text
/init
```

Claude 会扫描当前目录（现在是空的），并询问你几个问题，随后生成一份 `CLAUDE.md`。这份文件就是项目的"长期记忆"——它会在每次会话开始时自动加载，让 Claude 记住你项目的目标、技术栈和约定。

**预期结果**：目录下出现 `CLAUDE.md`，内容包含项目说明、构建命令、代码风格等结构化段落。

> 因为我们是从零开始，`/init` 此时主要搭好骨架。等会儿网页写出来后，你可以让它再 `/init` 一次，把真实技术栈写进去。

---

## 第六步：权限模式——给 Claude 划好"安全圈"

Claude Code 默认是**谨慎模式**：每动一个文件、跑一条命令都会先征求你同意。这很安全，但点确认点多了会累。系统提供四种模式，可用 **Shift+Tab** 在会话中循环切换，或用 `--permission-mode` 启动时指定：

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| `default`（默认） | 每个敏感操作都问 | 新手首跑、不熟悉的代码库 |
| `acceptEdits` | 自动接受文件编辑，命令仍要问 | 写代码为主时提效 |
| `plan` | 只读分析、不改文件，先给计划 | 复杂重构前先看方案 |
| `bypassPermissions` | 全自动，不再询问 | 受信任的自动化/CI（慎用） |

新手前几个项目，建议保持 `default` 或切到 `acceptEdits`。看到 Claude 想执行的命令，读一眼再按 `y` 放行——这是你理解它在做什么的最佳窗口。

也可以把常用安全命令加进 `settings.json` 的允许列表，免去重复确认：

```json
{
  "permissions": {
    "allow": ["Bash(open:*)", "Bash(ls:*)", "Read(*)"]
  }
}
```

---

## 第七步：实战——用一句话造出网页看板

主角登场。在 Claude Code 输入框里，直接用中文描述你的需求（自然语言就是编程语言）：

> 请帮我做一个单文件网页待办看板 index.html。三列：待办、进行中、已完成。顶部有输入框和"添加"按钮，能新建任务卡片。每张卡片有"右移"和"删除"两个按钮，右移按 待办→进行中→已完成 顺序流转。所有任务用 localStorage 持久化，刷新不丢。风格简洁现代，浅色主题，圆角卡片，有阴影。

Claude 会自动规划：创建文件 → 写 HTML 结构 → 写 CSS 样式 → 写 JS 逻辑 → 自检。每一步如果不在 `bypass` 模式，都会先征求你同意。一路 `y` 放行即可。

**预期结果**：目录下生成一个 `index.html`，双击用浏览器打开，看到一个带三列、可添加、可流转、刷新数据不丢的现代看板。

Claude 生成的核心代码大致长这样（节选），你可以打开文件对照学习：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>我的看板</title>
<style>
  * { box-sizing: border-box; font-family: system-ui, sans-serif; }
  body { margin: 0; background: #f4f5f7; color: #172b4d; padding: 24px; }
  h1 { text-align: center; }
  .toolbar { display: flex; gap: 8px; max-width: 720px; margin: 0 auto 24px; }
  .toolbar input { flex: 1; padding: 10px 12px; border: 1px solid #dfe1e6; border-radius: 8px; font-size: 15px; }
  .toolbar button { padding: 10px 20px; border: none; background: #0052cc; color: #fff; border-radius: 8px; cursor: pointer; font-size: 15px; }
  .board { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; max-width: 960px; margin: 0 auto; }
  .column { background: #ebecf0; border-radius: 12px; padding: 12px; min-height: 200px; }
  .column h2 { font-size: 14px; text-transform: uppercase; letter-spacing: .5px; margin: 4px 0 12px; }
  .card { background: #fff; border-radius: 8px; padding: 12px; margin-bottom: 8px; box-shadow: 0 1px 3px rgba(0,0,0,.12); }
  .card .text { margin-bottom: 10px; font-size: 15px; }
  .card .actions { display: flex; gap: 8px; }
  .card button { font-size: 12px; border: 1px solid #dfe1e6; background: #f4f5f7; border-radius: 6px; padding: 4px 10px; cursor: pointer; }
  .card button.del { color: #de350b; }
</style>
</head>
<body>
  <h1>📋 我的待办看板</h1>
  <div class="toolbar">
    <input id="taskInput" placeholder="输入新任务，回车添加…" />
    <button onclick="addTask()">添加</button>
  </div>
  <div class="board">
    <div class="column"><h2>待办</h2><div id="col-0"></div></div>
    <div class="column"><h2>进行中</h2><div id="col-1"></div></div>
    <div class="column"><h2>已完成</h2><div id="col-2"></div></div>
  </div>

<script>
const STAGES = ['待办', '进行中', '已完成'];
let tasks = JSON.parse(localStorage.getItem('kanban') || '[]');

function save() { localStorage.setItem('kanban', JSON.stringify(tasks)); }

function addTask() {
  const input = document.getElementById('taskInput');
  const text = input.value.trim();
  if (!text) return;
  tasks.push({ id: Date.now(), text, stage: 0 });
  input.value = '';
  save(); render();
}

function move(id) {
  const t = tasks.find(x => x.id === id);
  if (t && t.stage < 2) { t.stage++; save(); render(); }
}

function del(id) {
  tasks = tasks.filter(x => x.id !== id);
  save(); render();
}

function render() {
  STAGES.forEach((_, i) => document.getElementById('col-' + i).innerHTML = '');
  tasks.forEach(t => {
    const card = document.createElement('div');
    card.className = 'card';
    card.innerHTML = `<div class="text">${t.text}</div>
      <div class="actions">
        ${t.stage < 2 ? `<button onclick="move(${t.id})">右移 →</button>` : ''}
        <button class="del" onclick="del(${t.id})">删除</button>
      </div>`;
    document.getElementById('col-' + t.stage).appendChild(card);
  });
}

document.getElementById('taskInput').addEventListener('keydown', e => { if (e.key === 'Enter') addTask(); });
render();
</script>
</body>
</html>
```

### 让 Claude 帮你迭代

成果跑起来后，继续用自然语言提需求，体验"对话式开发"：

- "给每列加上任务数量徽标"
- "进行中那列加一个'暂停'按钮，能把任务退回待办"
- "换成深色主题，并支持点击徽标切换深浅色"

每提一条，Claude 就改一版代码，你刷新浏览器看效果。这就是 Claude Code 的核心快感——**你说人话，它写代码，你验成果**。

### 调试与自检

如果某个按钮没反应，直接把现象告诉它："进行中的'右移'按钮点了没反应"。Claude 会读取自己的代码、定位 bug（比如把 `move` 写成了 `mov`）、给你修复并说明原因。你也可以让它：

> 用浏览器打开 index.html 让我看看

它会调用 `open` 命令（已在允许列表则自动执行）。看 token 花费就敲 `/cost`。

---

## 工作流程图

下面这张图展示了从安装到交付看板的完整链路：

```text
flowchart TD
    A[确认 Node.js 环境] --> B{选择安装方式}
    B -->|原生安装器| C1[curl/irm 一键安装]
    B -->|npm| C2[npm i -g @anthropic-ai/claude-code]
    C1 --> D[运行 claude]
    C2 --> D
    D --> E[认证: 账号登录 或 API Key]
    E --> F[进入交互式 REPL]
    F --> G[新建项目目录 cd 进去]
    G --> H[/init 生成 CLAUDE.md 记忆]
    H --> I[Shift+Tab 选权限模式]
    I --> J[自然语言描述需求]
    J --> K[Claude 规划并写代码]
    K --> L{你确认放行?}
    L -->|y| M[生成 index.html]
    L -->|n| K
    M --> N[浏览器打开预览]
    N --> O{满意?}
    O -->|否, 提新需求| J
    O -->|是| P[交付成果 + /cost 看花费]
```

---

## 延伸阅读

- **Claude Code 官方快速开始**（中文）：`code.claude.com/docs/zh-CN/quickstart` —— 权威的第一手上手文档
- **官方 CLI 文档总览**：`docs.anthropic.com/en/docs/claude-code` —— 命令、配置、最佳实践全集
- **GitHub 仓库**：`github.com/anthropics/claude-code` —— README、更新日志、Issue
- **进阶方向**：掌握本篇后，可继续学习「CLAUDE.md 项目记忆」「权限与 settings.json」「子代理与 MCP 工具扩展」，把单兵作战升级为团队级自动化

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合的训练营类型 | **AI 编程入门营 / 全民 AI 素养营 / 校园开发者启蒙营 / 企业数字化转型通识营** |
| 学员基础要求 | 零编程基础即可，需会用命令行敲简单命令 |
| 预计教学时长 | **2~3 课时**（每课时 45 分钟）：1 课时装通+认证，1 课时配置与权限，1 课时造网页看板并迭代 |
| 实操产出 | 每人一个可运行的网页看板应用，可发到 GitHub Pages 展示 |
| 教学亮点 | 即时可视化反馈强、成就感高、自然语言门槛低，极易在营期内"出成果" |
| 注意事项 | 提前备好网络方案（代理或兼容网关）；准备备用 API Key 以防个别学员认证失败；建议每人配独立账号 |

---

## 参考来源

1. [快速开始 - Claude Code 官方文档（中文）](https://code.claude.com/docs/zh-CN/quickstart) — Anthropic 官方权威上手指南，涵盖安装、认证、核心命令
2. [Claude Code 2026 最新保姆级安装指南 - 腾讯云开发者社区](https://cloud.tencent.com/developer/article/2626713) — 多平台安装步骤与认证方式详解
3. [Claude Code 安装配置完整指南：Windows/Mac/Linux 全平台 + 国内 API 配置](https://zhuanlan.zhihu.com/p/2013750250721014697) — 含国内网络环境与兼容网关配置
4. [Claude Code 完整指南（一）：安装、CLI 实战、IDE 集成一次讲透 - CSDN](https://blog.csdn.net/qq_20042935/article/details/156649482) — CLI 实战操作与 IDE 集成演示
5. [【Claude Code 全攻略】终端AI编程助手从入门到进阶（2026最新版）- 阿里云开发者社区](https://developer.aliyun.com/article/1705912) — 核心功能、权限模式与最佳实践梳理

> [!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)