Claude Code原生安装与首个项目工程化

首页 › tutorials › Claude Code原生安装与首个项目工程化

概述

本教程面向从未用过 Claude Code、但已有基础终端和 Git 经验的开发者。学习目标只有一个：在 30 分钟内，用 2026 年官方推荐的「原生安装」方式装好 Claude Code，完成正确的认证决策，并把一个真实代码库初始化成「工程化」的 Claude Code 项目——写好 CLAUDE.md、配好权限、跑通第一个由 AI 交付的功能。我们不写"hello world"，我们交付一个可运行、可提交的功能。

前置条件

在开始前，请确认你具备以下基础和环境：

终端基础：能熟练使用 cd、ls、git，知道如何打开命令行。
一个代码项目：任何带 Git 仓库的真实工程（Node、Python、Go、Java 均可），不要求多复杂，但要有结构。
账户：Claude Pro/Max/Team/Enterprise 订阅，或 Claude Console（API 预付费）账户，或企业云（Amazon Bedrock / Google Vertex AI / Microsoft Foundry）访问权限，三者其一即可。
系统要求：macOS、Linux、WSL 或 Windows（Windows 原生建议预装 Git for Windows，以便 Claude Code 使用 Bash 工具）。
可选但强烈推荐：Visual Studio Code 或 JetBrains IDE（本教程不依赖，但工作流会更顺）。

核心理念：为什么 2026 年要「原生安装」而非 npm

很多 2024–2025 年的旧教程会教你 npm install -g @anthropic-ai/claude-code。这个命令在 2026 年依然有效，但已不再是官方首选。原因有三：

依赖污染：npm 全局安装要求本机有 Node.js ≥ 18，且 Claude Code 版本与全局 npm 包管理纠缠，升级时容易踩版本坑。
自动更新缺失：npm 全局包不会自动更新，你需要手动 npm update -g，容易停留在有已知问题的旧版本。
原生安装更轻：官方提供的 curl | bash、winget、brew --cask、apt/dnf/apk 等原生通道，在后台自动更新，始终保持在最新稳定版，且与系统包管理器一致。

决策原则：能用原生安装就用原生安装；只有在受限环境（无 root、无法执行 curl 脚本、必须用 npm 工作区）时才回退到 npm。

步骤 1：环境准备与系统检查

在安装前，先做一次环境体检，避免后面踩坑。

macOS / Linux / WSL：

# 检查 shell 与基础工具
echo $SHELL          # 期望 /bin/zsh 或 /bin/bash
git --version        # 期望有输出，没有就装 git
which curl           # 必须存在

Windows（PowerShell）：

$PSVersionTable.PSVersion   # 期望 5.1+ 或 PowerShell 7+
git --version               # 推荐安装 Git for Windows

常见问题：

现象	原因	解决
`'irm' is not recognized`	你在 CMD 里跑了 PowerShell 命令	改用 PowerShell，或用 CMD 专用命令
`&& is not a valid statement separator`	你在 PowerShell 里用了 CMD 语法	看提示符：`PS C:\` 是 PowerShell，`C:\` 是 CMD
`curl` 不存在（Windows CMD）	Windows CMD 的 curl 是别名	用官方提供的 CMD 专用安装脚本

小贴士：判断你在哪个 shell 的最快方法——看提示符。PS C:\Users\you> 是 PowerShell，C:\Users\you> 是 CMD。两者安装命令不同，别混用。

步骤 2：原生安装——四种主流方式详解

Claude Code 在 2026 年支持以下安装通道，按平台选择即可。

方式 A：curl 脚本（macOS / Linux / WSL，官方首选）

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

执行后，脚本会下载与系统架构匹配的二进制，放入用户级目录（通常是 ~/.local/bin 或 ~/.claude），并尝试写入 PATH。此方式后台自动更新，安装完一次即可长期使用。

方式 B：Windows 原生

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

:: CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

注意：WSL 环境请用方式 A 的 Linux 脚本，不要用 Windows 脚本，否则会装到 Windows 侧而非 Linux 发行版内。

方式 C：包管理器（brew / winget / apt / dnf / apk）

# macOS Homebrew
brew install --cask claude-code            # 稳定通道（约滞后一周）
brew install --cask claude-code@latest     # 最新通道

# Windows WinGet
winget install Anthropic.ClaudeCode

# Linux
sudo apt install claude-code        # Debian/Ubuntu
sudo dnf install claude-code        # Fedora/RHEL
sudo apk add claude-code            # Alpine

关键差异：brew --cask、winget、apt/dnf/apk 安装的版本不会自动更新，你需要定期手动 brew upgrade claude-code / winget upgrade Anthropic.ClaudeCode。只有 curl 脚本和 Windows 原生脚本会自动更新。如果你希望"装完不管"，优先选 curl 脚本。

方式 D：npm（回退方案，仅限受限环境）

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

需要 Node.js ≥ 18，无自动更新，需手动 npm update -g @anthropic-ai/claude-code。

验证安装

claude --version

看到版本号输出即安装成功。如果提示 command not found，多半是 PATH 未生效——重开终端，或手动把安装目录加入 PATH。

步骤 3：多路径认证——新手最容易选错的一步

Claude Code 必须登录才能使用，但它支持多种账户类型，新手最常在这一步困惑。下面帮你做一次清晰的决策。

认证方式全景

认证方式	适合谁	计费模型	首次登录行为
Claude Pro/Max/Team/Enterprise（推荐）	个人与团队开发者	按订阅套餐，Claude Code 用量计入套餐额度	浏览器跳转授权
Claude Console（API）	需要精确成本控制、程序化调用的开发者	按 token 预付费 credits	自动创建一个名为 "Claude Code" 的 workspace 用于成本追踪
Amazon Bedrock / Vertex AI / Microsoft Foundry	企业合规、数据驻留要求	走云厂商账单	需配置环境变量与厂商凭证

登录操作

安装后，在任意目录执行：

claude

首次运行会提示你选择账户并引导到浏览器完成授权。授权完成后，凭证会安全存储在本机，之后无需重复登录。

如果后续要切换账户或重新认证，在已运行的会话内输入：

/login

决策建议

不确定选哪个？ 选订阅（Pro/Max）。它最省心，不用算 token，适合 90% 的开发者。
公司给你报销 API？ 选 Console。首次登录会自动建好 "Claude Code" workspace，便于集中查成本。
公司有数据合规要求？ 选 Bedrock/Vertex/Foundry，让流量走你公司的云账号，不经过 Anthropic 直连。

重要：凭证存储是系统级的（macOS 用 Keychain，Linux 用 Secret Service，Windows 用 Credential Manager）。不要把 ANTHROPIC_API_KEY 之类的密钥硬编码进 shell 配置文件并提交到 Git——这是新手最常见的安全事故。

步骤 4：启动首个会话并完成「环境自检」

进入你的项目目录并启动：

cd /path/to/your/project
claude

你会看到一个提示符，上方显示版本号、当前模型、工作目录。先做三件事验证环境就绪：

/help

查看所有可用命令。

what can Claude Code do?

让 Claude 自述能力，顺便验证它真的读懂了你的项目。

what does this project do?

这是最关键的自检——如果 Claude 能准确概括你的项目用了哪些技术、入口在哪、目录结构如何，说明它能正常读取你的文件系统，环境完全就绪。

如果这一步 Claude 回答得驴唇不对马嘴，多半是当前目录不是 Git 仓库根目录，或目录权限有问题。回到步骤 1 检查 git status。

步骤 5：工程化初始化——把项目"改造"成 Claude Code 项目

这是本教程区别于普通入门教程的核心。光会启动 Claude Code 不够，你要让它在这个项目里持续高效、不出格、可复现。三件套缺一不可。

5.1 创建 `CLAUDE.md`（项目记忆与规约）

CLAUDE.md 是放在仓库根目录的 Markdown 文件，Claude Code 在每次会话启动时自动读取它。它相当于给 AI 的"项目说明书 + 行为准则"。

在一个已有项目里，最快的生成方式是让 Claude 自己写：

/init

Claude 会扫描代码库，生成一份初版 CLAUDE.md 草稿，覆盖：项目概述、技术栈、常用命令、目录结构、编码规范。审阅并修订它，重点补充三块：

绝对规约：用祈使句写明禁止事项，例如"不要自动 commit"、"修改代码后必须运行 npm test"。
常用命令：把测试、构建、lint 命令列清楚，避免 Claude 瞎猜。
领域知识：项目特有的业务规则、术语、外部依赖版本约束。

一份合格的 CLAUDE.md 不超过 200 行——太长会持续占用上下文窗口，反而拖慢响应、增加成本。

5.2 配置 `settings.json` 权限（安全护栏）

Claude Code 默认在修改文件、执行命令前征求你许可。但每次都确认很烦。通过 .claude/settings.json 可以预授权"安全操作"，把"高危操作"严格拦截。

在项目根目录创建 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(//**)",
      "Edit(src//**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Read(.env)",
      "Edit(.env)"
    ]
  }
}

语义说明：

allow：命中这些模式的命令自动放行，不再弹确认。
deny：命中这些模式的命令直接拒绝，连确认机会都不给——这是你的"红线"。
顺序很重要：deny 优先级高于 allow，所以即便你 allow 了 Bash(git:*)，deny 里的 Bash(git push:*) 依然会被拦。

权限层级：Claude Code 的 settings 有三层——用户级（~/.claude/settings.json，全局）、项目级（.claude/settings.json，进仓库共享）、本地项目级（.claude/settings.local.json，不进仓库，存个人偏好）。把团队共识放 settings.json，把个人机器差异（比如不同的测试脚本路径）放 settings.local.json，并在 .gitignore 里忽略后者。

5.3 把 `.claude/` 纳入版本控制

git add CLAUDE.md .claude/settings.json
git commit -m "chore: init Claude Code project context and permissions"

这样团队成员 git pull 后，开箱即用——同样的规约、同样的权限护栏、同样的记忆。settings.local.json 和 .env 永远不要提交。

步骤 6：交付第一个功能——并验证工程化是否生效

现在用一个真实小任务验证整条链路。假设你在一个 Node.js 项目里，让它新增一个"健康检查"端点：

在 src/routes 下新增一个 health 路由，GET /health 返回 JSON { status: "ok", timestamp: 当前ISO时间 }，
并在 app 入口注册它。完成后运行 npm test 验证，不要自动 commit。

预期行为：

Claude 先读 CLAUDE.md 和相关文件，理解项目结构。
它会找到 src/routes、找到入口文件。
展示拟修改，逐个征求你许可（命中 allow 的 Edit(src/**) 可能自动放行）。
写完代码后，运行 npm test（命中 allow，自动放行）。
不会自动 git commit——因为 CLAUDE.md 里写了禁止，且 git push 在 deny 里。

如果它试图 git push 或读 .env，你会看到权限被拒绝——这证明你的工程化护栏生效了。如果它试图自动 commit，说明 CLAUDE.md 的规约没生效，回去检查文件位置是否在仓库根目录。

常见问题与排障

Q：claude 命令装完提示 command not found？ A：PATH 没刷新。重开终端；或在当前 shell 手动 source ~/.zshrc（macOS）/ source ~/.bashrc（Linux）。确认安装路径（curl 脚本会在结束时打印）。

Q：登录后立刻报 401 / 认证失败？ A：多半是凭证过期或存储异常。会话内 /login 重新授权。企业用户检查 ANTHROPIC_BASE_URL、AWS_PROFILE、CLAUDE_CODE_OAUTH_TOKEN 等环境变量是否冲突。

Q：公司网络挡住了浏览器跳转？ A：终端会显示一个 URL 和授权码，手动复制到能上网的浏览器打开，输入授权码即可，不依赖自动跳转。

Q：Claude 总是自动 commit 怎么办？ A：CLAUDE.md 加一行"不要自动执行 git commit，只在我明确要求时提交"，并检查 .claude/settings.json 的 allow 里有没有误放 Bash(git commit:*)。

Q：Native 安装和 npm 装的会冲突吗？ A：会。两者都在 PATH 里时，谁在前谁先生效。建议二选一，先 npm uninstall -g @anthropic-ai/claude-code 再用原生安装。

Q：Windows 上 Claude Code 总用 PowerShell 而不是 Bash？ A：装 Git for Windows。装了之后 Claude Code 会优先用其自带的 Bash，跨平台脚本兼容性更好。

实战案例：从零交付一个 Express 健康检查端点

把上面所有步骤串起来，下面是一个完整的、可复现的实战。

起点：一个最小 Express 项目，结构如下：

myapp/
├── package.json
├── src/
│   ├── app.js          # express() 实例
│   └── routes/
│       └── users.js
└── test/
    └── health.test.js  # 空文件，待补充

操作序列：

cd myapp && claude 启动。
/init 生成并修订 CLAUDE.md，补入"测试命令 npm test、入口 src/app.js、禁止自动 commit"。
新建 .claude/settings.json，写入上文权限模板。
git add CLAUDE.md .claude/settings.json && git commit -m "init claude code context"。
输入需求：

在 src/routes/ 新建 health.js，导出一个返回 {status:"ok", timestamp} 的 router，
在 src/app.js 注册到 /health，并在 test/health.test.js 用 supertest 写一个通过测试。
完成后跑 npm test，不自动 commit。

预期结果：Claude 新建 src/routes/health.js、修改 src/app.js、填充 test/health.test.js，运行 npm test 全绿，然后把改动留在工作区等你审查——整个流程一气呵成，且全程在权限护栏内。

预期验证输出（示意）：

✓ GET /health 返回 200 且 body.status === "ok" (45ms)
1 passing

最后你亲自 git add -A && git commit 收尾。整个交付从"装好 Claude Code"到"绿测试 + 提交"不超过 30 分钟。

工作流程图

下面这张图把"从安装到交付首个功能"的完整路径可视化，可作为新手的心智模型。

flowchart TD
    A[环境自检<br/>git/curl/shell] --> B{选择安装方式}
    B -->|macOS/Linux/WSL| C1[curl install.sh]
    B -->|Windows| C2[irm install.ps1]
    B -->|包管理器| C3[brew/winget/apt]
    B -->|受限环境| C4[npm i -g]
    C1 --> D[claude --version 验证]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E{选择认证方式}
    E -->|个人/团队| F1[Pro/Max 订阅]
    E -->|精确控费| F2[Console API]
    E -->|企业合规| F3[Bedrock/Vertex/Foundry]
    F1 --> G[claude 启动 + 首个会话]
    F2 --> G
    F3 --> G
    G --> H["/init 生成 CLAUDE.md"]
    H --> I[配置 .claude/settings.json 权限]
    I --> J[git commit 工程化基线]
    J --> K[交付首个功能]
    K --> L{护栏是否拦截高危操作?}
    L -->|是| M[✅ 工程化生效]
    L -->|否| N[回查 CLAUDE.md/settings.json]
    N --> I

训练营适用性评估

维度	评估
适合的训练营类型	全栈/后端开发者入门营、AI 辅助开发训练营、企业内部开发效能培训、大学软件工程实践课
学员基础要求	会用终端和 Git，有一门后端语言基础；零 AI 工具经验可接受
建议教学时长	讲授 + 跟练 90 分钟（含 30 分钟实战交付）；可压缩到 60 分钟做"演示版"，或扩展到半天加 Skill/MCP 预习
实验产出	每人交付一个带 `CLAUDE.md` + 权限护栏 + 绿测试的工程化仓库，可作为后续所有课程的统一脚手架
不适合	完全无编程基础的人群（建议先补终端与一门语言）；纯前端且无后端项目可练的学员需另行准备 demo 仓库
衔接建议	本教程作为"第 0 课"，后续直接接 Skill 开发、MCP 集成、CI/CD 自动化三门进阶课

参考来源

Quickstart - Claude Code Docs — Anthropic 官方快速上手指南，本文安装、登录、八步流程的权威依据。
Advanced setup - Claude Code Docs — 官方原生安装各通道（curl/winget/brew/apt）与系统要求的细节来源。
Authentication - Claude Code Docs — 官方认证方式全景，本文多路径认证决策表的依据。
How to Install Claude Code: Complete Setup Guide (2026) — 第三方 2026 安装指南，交叉验证 npm/系统要求/API key 设置。
Claude Code Tutorial for Beginners 2026 (DEV Community) — 社区入门教程，提供从安装到首个项目的实践视角。

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

概述