本教程面向零基础用户，目标是在 macOS、Windows、Linux 三大平台用官方原生安装器装好 Claude Code，完成登录认证，建立"用户级—项目级—本地级"三层 settings.json 配置体系与权限围栏，并用一个真实可运行的小项目验证整套环境。全程只复制粘贴命令，不需要任何前置经验。适用人群：从未用过命令行的开发者、运维、网优、学生。预计 60 分钟读完并跑通。
在开始之前，确认你已经具备以下条件：
claude.ai 与 api.anthropic.com；国内网络通常需要代理。提示：如果你完全没用过终端，可先通读官方的 Terminal guide for new users（见文末参考来源），它专门为零基础用户讲解如何打开终端。
2025 年起，Anthropic 官方主推原生安装器（native installer），相比传统的 npm install -g @anthropic-ai/claude-code 有三个明显优势：
npm list -g 里塞入巨型依赖。claude update 一键升级，无需手动 npm install。原生安装器首次安装通常 30 秒内完成。下面分平台给出命令。
打开终端，执行：
curl -fsSL https://claude.ai/install.sh | bash
预期结果：脚本会下载二进制文件到 ~/.local/bin/claude（部分系统是 /usr/local/bin），并提示你将对应目录加入 PATH。安装结束后执行版本检查：
claude --version
正常情况下会输出类似 2.x.x 的版本号。
常见问题与解决：
| 现象 | 原因 | 解决 |
|---|---|---|
claude: command not found |
PATH 未刷新 | export PATH="$HOME/.local/bin:$PATH"，并写入 ~/.zshrc 或 ~/.bashrc 后 source 一次 |
curl: (7) Failed to connect to claude.ai |
网络不通/被墙 | 配置代理：export https_proxy=http://127.0.0.1:7890 后重试 |
| 下载到一半中断 | 网络抖动 | 重新执行同一条命令，安装器会续传覆盖 |
以普通用户身份打开 PowerShell（不需要管理员），执行：
irm https://claude.ai/install.ps1 | iex
预期结果：脚本把程序下载到 %LOCALAPPDATA%\Programs\claude，并自动把该路径写入用户级 PATH。关闭并重新打开一个 PowerShell 窗口后，claude --version 应能正常输出版本号。
常见问题与解决：
running scripts is disabled）：执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，再重试。D:\projects\），避免 C:\Users\张三\ 这类路径。如果你所在企业网络只能走内网 npm 镜像、或已经装好 Node.js 18+，也可以用经典方式：
npm install -g @anthropic-ai/claude-code
国内开发者常配合镜像加速：
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
安装后同样执行 claude --version 验证。这种方式升级用 claude update 或 npm install -g @anthropic-ai/claude-code@latest。
Claude Code 支持两种认证方式，按你的账号类型选择：
路径 A：订阅登录（Pro/Max 包月）
claude
首次进入会询问认证方式，选择 Claude account，终端会输出一个 URL 并尝试自动打开浏览器。在浏览器里完成 claude.ai 授权后，回到终端即登录成功。这种方式按订阅额度计费，不需要任何 API Key，最适合个人开发者日常使用。
路径 B：API Key（按量计费）
先到 console.anthropic.com 创建一个 API Key（以 sk-ant- 开头），然后：
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"
claude
按 token 用量计费，适合脚本、CI/CD 自动化或多人共享一个 key 的场景。建议把 export 写进 shell 配置文件持久化。
claude
> /status
预期结果：/status 会显示当前登录账号、所用模型、订阅或 API 状态、剩余额度等信息。看到账号信息即代表登录成功。
常见问题与解决：
Invalid API key：检查 key 是否完整复制（不要漏掉前缀和尾部字符）、是否包含换行。Unable to verify authentication：多为网络问题，确认代理对 api.anthropic.com 生效。Claude Code 的强大之处在于它的配置是分层叠加的。完整优先级从高到低是：企业托管（managed）> 项目本地 > 项目共享 > 用户全局。入门阶段只需掌握后三层。
| 层级 | 路径 | 用途 | 是否提交 git |
|---|---|---|---|
| 用户全局 | ~/.claude/settings.json |
个人默认值：主题、默认模型、通用放行规则 | 否 |
| 项目共享 | <项目根>/.claude/settings.json |
团队统一配置，clone 即生效 | 是 |
| 项目本地 | <项目根>/.claude/settings.local.json |
个人覆盖、含密钥的 env，互不干扰 | 否（需 gitignore） |
关键认知：同名配置，高优先级覆盖低优先级。这意味着你可以把团队规范放项目共享层、把个人密钥放本地层，两者互不污染。
进入交互会话后，三个命令覆盖 90% 的日常配置需求：
/config——打开设置面板，切换主题、默认模型、通知方式。/permissions——查看、新增、删除权限规则。/model——快速切换当前会话模型。新手优先用斜杠命令，熟练后再直接编辑 JSON 文件。
用编辑器打开 ~/.claude/settings.json（不存在就新建），写入：
{
"model": "claude-sonnet-4-6",
"theme": "dark",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff:*)",
"Read(./**)"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./**/*.pem)"
],
"defaultMode": "default"
},
"env": {
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192"
}
}
权限规则语法统一为 ToolName(specifier)：
Bash(npm test) 只放行这一条命令。Bash(npm run *) 放行所有 npm run 脚本。Read(./src/**) 放行 src 目录下全部文件。四种权限模式（由 defaultMode 或启动参数 --permission-mode 控制）：
| 模式 | 行为 | 适用场景 |
|---|---|---|
default |
每个写操作都询问 | 入门首选，最安全 |
acceptEdits |
自动接受文件编辑，命令仍询问 | 批量改代码 |
plan |
只读规划，绝不改文件 | 方案设计、代码审查 |
bypassPermissions |
跳过所有检查 | 仅限一次性沙箱容器 |
安全建议：入门阶段保持
default，把危险命令（rm -rf、git push --force）和敏感文件（.env、*.pem、*.key）写进deny，形成"白名单 + 黑名单"双保险。
目标：从零让 Claude Code 生成一个"中文 Markdown 转 HTML 预览"的命令行小工具——单文件、零依赖、可直接运行。整个过程不需要你写一行代码。
mkdir md2html && cd md2html
git init
claude
进入交互会话后，你会在 md2html 目录里启动 Claude Code。
在交互框里输入：
帮我写一个 Node.js 单文件脚本 md2html.js：读取命令行参数指定的 .md 文件，
把标题、无序列表、有序列表、加粗、行内代码、代码块转换成 HTML，
输出同名的 .html 文件，并在终端打印生成路径。不要使用任何第三方依赖，
纯标准库实现。
Claude Code 会按以下步骤工作：
Write 工具创建 md2html.js。sample.md 示例文件方便测试。node md2html.js sample.md——由于 defaultMode=default，这里需要你按 y 批准。sample.html，终端打印"已生成 sample.html"。你可以在新窗口用浏览器打开 sample.html 查看渲染效果。
手动复跑一次，确认脚本独立可用：
node md2html.js sample.md
常见问题与解决：
EACCES 或 Permission denied）：在 /permissions 面板把 Bash(node md2html.js *) 加入 allow；或直接对这一条按 y 放行并选择"始终允许"。<head> 加上 <meta charset='utf-8'>"，它会自动改文件。--watch 参数，文件变化时自动重新生成"，让 Claude 增强功能。/model 切换模型，或在需求里加"先解释你的实现思路再写代码"。为了让团队成员 clone 后共享同一套放行规则，编辑项目根的 .claude/settings.json：
{
"permissions": {
"allow": [
"Bash(node md2html.js *)",
"Bash(git add:*)",
"Bash(git commit:*)"
],
"deny": [
"Bash(rm -rf *)"
]
}
}
然后提交：
git add .claude/settings.json md2html.js sample.md
git commit -m "init: md2html 工具与项目权限配置"
同时务必把
.claude/settings.local.json加入.gitignore，避免把个人密钥提交到仓库。这就是"共享层进 git、本地层不进 git"的实践要点。
下面这张图概括了从环境检查到首项目落地的完整流程，可作为你的"首日上手脚册"打印对照：
flowchart TD
A[前置检查: 网络 / 账号 / 终端] --> B{选择安装方式}
B -->|macOS/Linux/WSL| C[curl 原生安装器]
B -->|Windows| D[irm 原生安装器]
B -->|已有 Node.js| E[npm 全局安装]
C --> F[claude --version 验证]
D --> F
E --> F
F --> G[登录认证]
G --> G1[订阅登录: 浏览器授权]
G --> G2[API Key: export ANTHROPIC_API_KEY]
G1 --> H[/status 确认账号]
G2 --> H
H --> I[配置: 用户级 settings.json]
I --> I1[设默认模型 / 主题]
I --> I2[配 allow 白名单]
I --> I3[配 deny 黑名单]
I1 --> J[建项目目录 + git init]
I2 --> J
I3 --> J
J --> K[claude 下需求]
K --> L[审批权限 + 运行]
L --> M{验证通过?}
M -->|否, 继续追问修改| K
M -->|是| N[权限固化进项目共享配置]
N --> O[git add + commit]
code.claude.com/docs/en/quickstart——官方权威的首会话演练。code.claude.com/docs/en/terminal-guide——零基础如何打开终端、跑通第一条命令。code.claude.com/docs/en/setup——系统要求、平台细节、版本管理与卸载。code.claude.com/docs/en/permissions——细粒度权限规则、模式与托管策略的完整说明。| 维度 | 评估 |
|---|---|
| 适用训练营类型 | "AI 编程入门营""开发者工具速成营""通信/网优工程师 AI 提效营""高校新生数字化素养营" |
| 学员基础要求 | 零基础可学，会复制粘贴命令即可；有终端经验者 30 分钟可跑通 |
| 建议教学时长 | 集中讲授 45 分钟 + 动手实操 60 分钟 + 答疑 15 分钟，共约 2 课时 |
| 交付物 | 每位学员产出一个可运行的 md2html 小工具 + 一份个人 settings.json 配置文件 |
| 考核点 | ① claude --version 正常；② /status 显示已登录；③ 能用一句话让 Claude 生成并运行代码；④ 能正确区分三层配置文件的提交策略 |
| 常见卡点 | 国内网络代理、Windows 执行策略、API Key 复制不完整——建议讲师提前准备代理与备用账号 |
本文由「51学通信」站长爱卫生（微信：gprshome201101）整理，聚焦让零基础开发者真正跑通第一个 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 等场景全覆盖。