首页 › tutorials › Claude Code入门：从环境自检到首个功能

Claude Code 入门：从环境自检到首个功能落地

概述

本教程面向完全零基础的开发者，目标是让你在一小时内完成 Claude Code 的环境检查、安装、认证，并端到端交付一个真实可运行的命令行小工具。学完后你能独立判断本机环境是否达标、选择正确的安装与认证方式、跑通 /doctor 自检，并理解 settings.json 与 .claude 目录的组织方式。全程不依赖任何框架，跟着敲命令即可。

前置条件

在动手之前，请确认你具备以下条件，缺一不可：

操作系统：macOS 12+、主流 Linux 发行版（Ubuntu 20.04+ / Debian / Arch 等），或 Windows 10/11（必须通过 WSL2 运行，原生 cmd/PowerShell 暂不是一等公民）。
Node.js：18 及以上版本，推荐 20 LTS。Claude Code 是用 Node 编写的 CLI，没有 Node 跑不起来。
终端基础：会用 cd 切目录、ls 看文件、mkdir 建目录。不需要会写 shell 脚本。
账号：一个 Anthropic 账号。两条路径二选一——① 已订阅 Claude Pro / Max 套餐；② 或拥有 Anthropic API key（控制台 console.anthropic.com 申请，需充值余额）。
网络：能访问 api.anthropic.com 与 claude.ai。若你在受限网络环境，需要预先配置 HTTP(S) 代理（后文会讲）。

如果你对上述任何一项不确定，本教程的第一步就是教你怎么逐项排查。

第一步：环境自检（别跳过这一步）

绝大多数"装不上、跑不起来"的问题，根因都在环境。花三分钟自查，能省后面三小时的排查。

1.1 检查 Node 版本

打开终端，执行：

node --version

预期结果：输出形如 v20.11.0 或 v18.19.0。

常见问题： - 提示 command not found → 没装 Node。用 fnm（推荐，快且跨平台）安装：

bash curl -fsSL https://fnm.vercel.app/install | bash exec $SHELL fnm install 20 fnm use 20

版本低于 18（如 v16.x）→ Claude Code 拒绝启动。执行 fnm install 20 && fnm use 20 升级。

1.2 检查 npm 全局目录权限

npm config get prefix

如果输出指向 /usr/local 或 /usr，说明你用的是系统 Node，npm install -g 会要求 sudo，后续极容易踩"权限拒绝"的坑。建议把全局前缀改到你的家目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc   # zsh 用户改 ~/.zshrc
source ~/.bashrc

1.3 检查网络与代理

执行一次连通性测试：

curl -sS -o /dev/null -w "%{http_code}\n" https://api.anthropic.com

预期结果：返回 401（未授权但能连通）或 404，只要不是超时即代表网络通。

常见问题：长时间无响应或报 Could not resolve host → 你处于受限网络。配置代理环境变量：

export HTTPS_PROXY=http://127.0.0.1:7890   # 改成你本机代理端口
export HTTP_PROXY=http://127.0.0.1:7890

把这两行追加到 ~/.bashrc 持久化。Claude Code 会读取 HTTPS_PROXY 走代理。

小提示：代理端口因工具而异（Clash 默认 7890、V2Ray 常见 10809）。确认端口的方法：打开你的代理客户端，查看"本地监听端口"。

第二步：安装 Claude Code

Claude Code 提供两种官方安装方式。新手用 npm，老手或离线机器用原生安装包。

方式 A：npm 全局安装（推荐）

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

预期结果：末尾出现 added X packages，无 npm ERR!。

验证安装：

claude --version

看到版本号（如 1.0.x）即安装成功。

常见问题： - EACCES: permission denied → 回到 1.2 修复全局目录权限，或临时加 sudo（不推荐，长期会有麻烦）。 - 安装卡住 → 多半是 npm 源问题，临时换源：npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com。

方式 B：原生安装（零 Node 依赖）

适合不想装 Node、或在隔离服务器上部署的场景。macOS / Linux 一行命令：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell（不需要 WSL 的轻量场景）：

irm https://claude.ai/install.ps1 | iex

预期结果：脚本下载预编译二进制到 ~/.local/bin/claude（或 $HOME/.claude/local），并尝试加入 PATH。

常见问题： - 装完执行 claude 提示 command not found → 二进制所在目录不在 PATH。把 ~/.local/bin 加入 PATH：echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc && source ~/.bashrc。

方式 C：IDE 插件（VS Code / JetBrains）

在 VS Code 扩展市场搜索 "Claude Code" 安装，或在 JetBrains 插件仓库搜索安装。插件本质上是调用本地 claude 二进制，所以仍需先用方式 A 或 B 装好 CLI。本教程以终端为主，IDE 插件留作后续探索。

第三步：首次认证

认证决定 Claude Code 用哪个账号的额度。两种方式，按你的订阅情况二选一。

路径 ①：Pro / Max 订阅登录（最省心）

如果你已经付费订阅了 Claude Pro 或 Max，直接：

claude

首次启动会提示你按回车打开浏览器，完成 OAuth 授权后回到终端，看到欢迎界面即登录成功。

验证登录状态：

# 在 Claude Code 交互界面内输入
/status

预期结果：显示你的账号邮箱、订阅类型、当前会话模型、剩余额度上下文窗口等信息。

路径 ②：API Key 方式（适合企业 / 无订阅用户）

去 console.anthropic.com → Settings → API Keys → Create Key，复制以 sk-ant- 开头的密钥。然后：

export ANTHROPIC_API_KEY=sk-ant-xxxxxx你的密钥xxxxxx

为避免每次开终端都要 export，写入 shell 配置：

echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxxx' >> ~/.bashrc
source ~/.bashrc

安全提醒：切勿把 API Key 提交进 git、写进项目里的 .env 并推到公开仓库。一旦泄露立刻在控制台吊销重建。

常见问题： - 浏览器授权页打不开（无图形界面服务器）→ 用 API Key 方式，或在本地浏览器授权后复制粘贴终端提示的授权码。 - 401 Unauthorized → Key 输错或已过期；订阅用户检查是否还在订阅期内。

第四步：环境诊断 /doctor

Claude Code 内置了体检命令，强烈建议装完先跑一次：

在交互界面内输入：

/doctor

它会逐项检查：Node 版本、CLI 版本、OS 兼容性、网络连通性、认证状态、git 是否可用、权限配置是否健康。每项给出 ✓ 或 ✗ 与修复建议。

预期结果：全部 ✓，显示 "Your Claude Code setup looks healthy!"。

常见问题： - 网络项 ✗ → 回到第一步 1.3 配代理。 - 认证项 ✗ → 回到第三步重新登录或重新设置 API Key。 - git 项 ✗ → 安装 git：sudo apt install git（Debian/Ubuntu）或 brew install git（macOS）。

第五步：第一个项目实战——待办命令行工具

现在环境齐活，我们来用 Claude Code 端到端做一个真实项目：一个 Node.js 写的命令行待办工具 todo，支持 add / list / done 三个子命令，数据存在本地 JSON 文件，最后加上单元测试。整个过程我们只说需求，代码交给 Claude Code。

5.1 建项目并进入

mkdir ~/my-todo && cd ~/my-todo
git init                          # Claude Code 强依赖 git，务必初始化
claude                            # 启动交互界面

为什么强调 git init？Claude Code 大量功能（差异查看、回滚、安全护栏）都建立在 git 之上。没有 git 仓库，它的能力会大打折扣。

5.2 第一次提需求

在交互界面里直接输入这段话（不用学任何特殊语法，自然语言即可）：

帮我用 Node.js 做一个命令行待办工具。
要求：
1. 单文件 todo.js，用 #!/usr/bin/env node 作为 shebang。
2. 子命令：todo add "内容" 添加任务；todo list 刓出所有任务；todo done <序号> 标记完成。
3. 数据存在同目录 .todos.json 文件里，没有就自动创建。
4. 不要用任何第三方依赖，只用 Node 内置模块。
5. 每个任务有 id、text、done 三个字段。

按回车，观察 Claude Code 的行为：它会先用工具读取目录、查看是否已有文件，然后写出 todo.js，并解释每段代码。完成后会在终端显示创建的文件与改动。

预期结果：项目目录下出现 todo.js。Claude Code 通常还会顺手把它标记为可执行 chmod +x。

5.3 运行验证

暂时退出交互界面（Ctrl+C 两次，或输入 /exit），在普通 shell 测试：

node todo.js add "读完 Claude Code 入门教程"
node todo.js add "用 Claude Code 做第一个项目"
node todo.js list
node todo.js done 1
node todo.js list

预期结果：list 先显示两条未完成任务；done 1 后再次 list，第一条被标记为 [x] 完成，并能看到 .todos.json 文件被创建。

5.4 回去修 bug / 加功能

回到 Claude Code（再次 claude），用 @ 引用文件来精确定位上下文：

看一下 @todo.js，现在 list 是按插入顺序显示的。帮我改成：未完成的排前面，已完成的排后面；并且每行前面显示序号。

Claude Code 会读取 todo.js，定位到 list 相关逻辑，给出修改。

5.5 加单元测试

给 @todo.js 加单元测试，用 Node 内置的 node:test 和 node:assert，不要引入 jest。把测试逻辑抽到一个可测的纯函数模块里（比如把任务管理逻辑放到单独文件），保证测试不依赖文件系统副作用。

预期结果：Claude Code 会建议把核心逻辑（增删改查）重构为一个纯函数模块，再写测试文件。然后它会主动提示你运行：

node --test

看到 tests N passed (N) 即测试全绿。

这一步体现了 Claude Code 的一个关键习惯：让它自己运行验证。修改代码后，如果有测试命令，它会主动跑测试并把结果反馈进上下文，形成"改→测→改"的闭环，而不是让你手动验证。

第六步：理解 settings.json 与 .claude 目录

跑通项目后，了解配置体系能让你后续用得更顺。Claude Code 的配置分三个层级，优先级从高到低：

层级	路径	用途
企业级	`/Library/Application Support/ClaudeCode/managed-settings.json`（macOS）等	公司统一下发的强制策略
用户级	`~/.claude/settings.json`	你的个人全局偏好
项目级	`<项目>/.claude/settings.json`	随仓库提交、团队共享
本地级	`<项目>/.claude/settings.local.json`	个人覆盖，应加入 `.gitignore`

一个典型的用户级 ~/.claude/settings.json 长这样：

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(node --test)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ]
  },
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}

model：默认模型。
permissions.allow：预授权这些命令，执行时不再每次弹窗确认——这是减少打断、提升流畅度的核心配置。
permissions.deny：硬禁止，任何情况都不许执行。
env：注入环境变量（如代理）。

此外还有两个重要文件： - CLAUDE.md：项目级的"长期记忆"，写在仓库根目录。里面记录项目约定、技术栈、命令、注意事项。Claude Code 每次启动会自动读入。本教程第一个项目里，你可以让它执行 /init 自动生成一份 CLAUDE.md。 - ~/.claude/CLAUDE.md：你的全局个人记忆，所有项目共享。

在交互界面输入 /init，Claude Code 会扫描项目并起草一份 CLAUDE.md，你确认后它就落盘。

第七步：常用斜杠命令速查

掌握这几个，日常就够用了：

命令	作用
`/help`	查看所有命令
`/status`	查看账号、模型、额度
`/doctor`	环境自检
`/config`	打开/编辑配置
`/clear`	清空当前会话上下文（换任务前必用，省 Token）
`/compact`	压缩上下文（会话太长时用，保留要点）
`/cost`	查看本次会话 Token 消耗
`/init`	为当前项目生成 CLAUDE.md
`/login` `/logout`	切换账号

还有两个非斜杠的交互技巧： - 输入 @ 会弹出文件选择器，引用具体文件给 Claude Code 当上下文。 - 输入 # 开头的一句话，会把它追加进 CLAUDE.md 作为长期记忆。

常见报错速查表

报错	原因	解决
`command not found: claude`	二进制不在 PATH	修复 PATH（见方式 B 常见问题）
`EACCES permission denied`	npm 全局目录无写权限	见 1.2 改 prefix
`401 Unauthorized`	认证失败	重新 `/login` 或检查 API Key
`ENOTFOUND api.anthropic.com`	DNS/网络不通	配置 `HTTPS_PROXY`
`Node version too old`	Node < 18	用 fnm 升级到 20
`Overloaded` / `529`	服务端过载	稍等重试，或切其他模型

整体上手流程图

下面这张图概括了从零到跑通第一个项目的完整路径，遇到卡点可对照定位你在哪一环：

flowchart TD
    A[零基础起点] --> B{环境自检}
    B -->|Node≥18?| C1[✓ 继续]
    B -->|否| C2[fnm install 20]
    C2 --> B
    C1 --> D{npm 权限正常?}
    D -->|否| E[改全局 prefix]
    E --> D
    D -->|是| F[安装 Claude Code]
    F --> G{网络通?}
    G -->|否| H[配置 HTTPS_PROXY]
    H --> G
    G -->|是| I[首次认证]
    I --> J{Pro/Max 订阅?}
    J -->|是| K1[claude 浏览器登录]
    J -->|否| K2[设置 ANTHROPIC_API_KEY]
    K1 --> L[/doctor 体检全绿/]
    K2 --> L
    L --> M[mkdir 项目 + git init]
    M --> N[claude 启动 + 提需求]
    N --> O[Claude Code 写代码]
    O --> P[node 运行验证]
    P --> Q{符合预期?}
    Q -->|否| R[回交互界面描述问题修 bug]
    R --> P
    Q -->|是| S[/init 生成 CLAUDE.md]
    S --> T[✅ 第一个功能落地]

小结

走到这里，你已经完成了零基础到"能交付一个功能"的完整闭环：环境自检、安装、认证、体检、用自然语言驱动开发、运行验证、配置体系。Claude Code 的核心理念是——你只描述意图，它负责读代码、改代码、跑测试、反馈结果。把繁琐的机械操作交给它，把判断和决策留给自己。后续要深入，可以从斜杠命令、CLAUDE.md 记忆体系、-p 非交互自动化、Hooks、Subagent 这些方向逐个解锁。

参考来源

Anthropic Claude Code 官方文档 — 安装、配置、命令的权威说明，本文安装方式与斜杠命令的主要依据。
Claude Code Settings 官方参考 — settings.json 三级配置层级与环境变量注入规范。
@anthropic-ai/claude-code — npm — npm 全局安装的官方包页面与版本信息。
Anthropic 官方博客：Claude Code 发布 — 产品定位与设计理念。
Claude Code GitHub 仓库 — 问题追踪与版本更新日志。

训练营适用性评估

适合的训练营类型：① 零基础开发者入门营（重点）；② 企业内部 AI 编程赋能营的"破冰第一课"；③ 高校编程实践课导论模块；④ 转岗/跨界人员的 AI 工具速成营。
不适合：已有 Claude Code 使用经验的中高级营（内容会过于基础，应直接进阶到 Hooks / Subagent / MCP）。
预计教学时长：讲授 + 跟做约 90–120 分钟。其中环境自检与安装 30 分钟、认证与体检 15 分钟、第一个项目实战 45–60 分钟、配置体系讲解 15 分钟。
前置作业建议：学员课前自行完成 Node 安装与 Anthropic 账号注册，可节省 20 分钟课堂时间。
考核点：能独立让 Claude Code 产出一个可运行、带测试的小工具，并正确配置 permissions.allow 减少弹窗。

[!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学通信知识星球海报-扫码加入