这是一篇面向 Mac 用户的 Claude Code 安装配置教程，完整讲清终端准备、原生安装脚本、Homebrew 安装、权限确认、项目目录选择、Git 检查、CLAUDE.md 项目规则和常见报错排查。
摘要：Mac 安装 Claude Code，关键不只是装上命令
很多 Mac 用户安装 Claude Code 时，只关注一条安装命令是否成功，却忽略了三个更影响后续体验的细节：终端环境是否能找到 claude 命令、权限提示是否理解清楚、项目目录是否选在正确的仓库根目录。只要这三件事没处理好，后面就容易遇到 command not found、无法读取项目、误改文件、上下文混乱、Claude 看不懂项目结构等问题。
本文按实际上手顺序讲清楚 Mac 安装 Claude Code 的完整流程：先确认 macOS 与终端环境，再选择官方原生安装脚本或 Homebrew 安装；随后完成登录、版本检查、PATH 检查、Git 检查、项目目录初始化和权限策略设置。正文示例全部围绕 Mac 终端、权限、项目目录展开，适合第一次在 Mac 上配置 Claude Code 的用户。
如果你还没有看过综合版安装说明，可以先读站内的 Claude Code 安装配置教程：Windows / Mac 从零开始；如果你已经完成安装，想继续学习提示词和项目开发流程，可以接着看 Claude Code 从入门到实战：一篇文章讲清安装、提示词和项目开发。Windows 用户则可以参考 Claude Code Windows 安装教程：WSL、Git Bash、Node 环境完整配置。
安装前准备：先把 Mac 终端环境理顺
确认 macOS 版本
Claude Code 官方安装文档要求 macOS 13.0 或更高版本。你可以点击左上角苹果菜单，进入“关于本机”查看系统版本；也可以在终端执行：
sw_vers如果系统低于 macOS 13，建议先升级系统，再继续安装。旧系统上即使某些命令能执行，也可能在认证、权限、依赖或后续升级时遇到不可预期的问题。
选择终端：Terminal 或 iTerm2 都可以
Mac 自带 Terminal 已经足够使用 Claude Code。你也可以使用 iTerm2，但新手不需要为了安装 Claude Code 专门更换终端。关键不是终端品牌，而是你知道当前 shell 是什么、命令是否在 PATH 中、项目目录在哪里。
查看当前 shell：
echo $SHELL大多数新版本 macOS 默认是 zsh。如果你后面遇到命令找不到，通常要检查 ~/.zshrc、~/.zprofile 或 Homebrew 的 shellenv 配置。
确认 Git 与开发工具
Claude Code 可以读取项目文件、理解代码结构、帮你修改代码和运行命令。对于真实项目，Git 几乎是必需的基础工具。先检查 Git：
git --version如果系统提示需要安装 Command Line Tools，按提示安装即可；也可以手动执行：
xcode-select --install安装完成后重新打开终端，再次执行 git --version。如果你要在 Node、Python、Go、Rust 等项目中使用 Claude Code，也建议先把对应语言运行时配置好。
安装方式一：使用官方原生安装脚本
执行安装命令
在 macOS 终端中执行官方安装命令：
curl -fsSL https://claude.ai/install.sh | bash这条命令会下载并执行 Claude Code 安装脚本。安装完成后，关闭当前终端窗口并重新打开一个新的终端窗口，让 shell 重新加载环境变量。
验证 claude 命令
重新打开终端后执行：
claude --version如果能看到版本号，说明命令已经可用。接着检查命令路径：
which claude这个路径可以帮助你判断 Claude Code 是通过脚本安装、Homebrew 安装，还是来自其他历史安装残留。排查环境问题时，which claude 比单纯看版本号更有价值。
首次启动与登录
进入一个测试目录，执行：
claude首次启动时，Claude Code 会引导你完成登录或认证。登录完成后，你可以在 Claude Code 交互界面中使用 /status 查看当前状态。不要在未知目录里直接让它修改文件，第一次建议只做只读检查任务。
安装方式二：使用 Homebrew 安装
先确认 Homebrew 可用
如果你的 Mac 已经安装 Homebrew，可以执行：
brew --version如果提示 brew: command not found，说明 Homebrew 尚未安装，或者 Homebrew 路径没有加入 shell 环境。Apple Silicon Mac 常见路径是 /opt/homebrew/bin/brew，Intel Mac 常见路径是 /usr/local/bin/brew。
使用 Homebrew 安装 Claude Code
使用 Homebrew cask 安装：
brew install --cask claude-code如果你希望始终安装最新渠道，可以使用：
brew install --cask claude-code@latest安装完成后同样执行：
claude --version
which claude更新 Claude Code
如果是 Homebrew 安装，可以用 Homebrew 更新：
brew upgrade --cask claude-code如果使用的是最新渠道 cask，则按对应 cask 名称升级。升级后重新打开终端，再执行 claude --version 确认版本。
终端 PATH 排查：解决 command not found
第一步：重开终端
安装脚本或 Homebrew 可能会写入 shell 配置，但当前终端会话不一定立即加载。安装后先关闭所有终端窗口，重新打开，再执行：
claude --version第二步：检查 shell 配置
如果仍然提示 command not found: claude，先检查当前 shell：
echo $SHELL如果是 zsh，再检查：
echo $PATH如果你使用 Homebrew，Apple Silicon Mac 可以尝试加载 Homebrew 环境：
eval "$(/opt/homebrew/bin/brew shellenv)"Intel Mac 可以尝试：
eval "$(/usr/local/bin/brew shellenv)"确认可用后，再把对应 shellenv 写入 ~/.zprofile，避免每次新开终端都要手动执行。
第三步：避免多版本混乱
如果你既用过官方脚本，又用过 Homebrew，可能会出现多个 claude 路径。用下面命令检查：
which -a claude如果出现多个路径，优先保留当前想使用的安装方式，并按官方说明清理旧版本。不要随意删除系统目录里的文件；如果不确定，先记录路径，再做卸载或重装。
权限设置：读文件、改文件、运行命令要分清
Claude Code 是面向真实项目的编码助手，它不仅能聊天，还可能读取项目文件、编辑文件、执行命令、运行测试。Mac 用户第一次使用时，最容易把系统权限、项目权限和 Claude Code 的操作确认混在一起。正确做法是把权限分成三层理解。
第一层：macOS 系统权限
如果终端无法访问某些目录，macOS 可能会弹出权限提示。一般开发项目建议放在 ~/Projects、~/Developer 或用户主目录下的专门工作区，而不是放在系统目录、iCloud 同步目录或权限复杂的位置。
如果你把项目放在桌面、文稿、下载等目录，macOS 隐私权限可能会影响终端读取。新手更推荐建立一个独立开发目录：
mkdir -p ~/Projects
cd ~/Projects第二层：Claude Code 操作确认
当 Claude Code 准备执行可能修改文件或运行命令的操作时，通常会向你确认。确认前要看清楚三件事：它要改哪些文件、要运行什么命令、命令是否会访问网络或删除内容。
建议新手给 Claude Code 的第一条任务不要要求它直接修改代码，而是先让它只读分析：
请先只读分析这个项目，不要修改文件。请告诉我项目结构、启动命令、测试命令和你建议我先处理的 3 个问题。第三层：项目级规则
对于长期项目，建议在项目根目录写一份 CLAUDE.md，说明项目规则、测试命令、禁止事项和常用工作流。这样 Claude Code 每次进入项目时可以获得稳定上下文。
# Project Rules
- 使用 npm 作为包管理器。
- 修改前先阅读 README.md 和 package.json。
- 修改后运行 npm test。
- 不要读取、打印或提交 .env、密钥、账号密码。
- 不要执行删除数据库、清空线上数据或直接发布生产环境的命令。
- 所有改动先给出计划，确认后再修改。如果你想看更多 Claude Code 在真实开发中的工作方式，可以阅读站内 Claude Code 最适合做什么？10 个真实开发场景完整演示。
项目目录设置：一定要从仓库根目录启动
推荐目录结构
建议在用户目录下建立固定项目文件夹，例如：
mkdir -p ~/Projects
cd ~/Projects
git clone [email protected]:your-name/your-project.git
cd your-project如果你还没有远程仓库，也可以先创建本地目录：
mkdir my-app
cd my-app
git init启动前先检查 Git 状态
进入项目后先执行：
pwd
git status
lspwd 用来确认你所在目录，git status 用来确认仓库状态，ls 用来快速查看项目根目录是否包含 README、package.json、pyproject.toml、src 等关键文件。如果你在错误目录启动 Claude Code，它看到的上下文就会偏离真实项目。
从项目根目录启动 Claude Code
确认目录无误后执行：
claude进入交互界面后，第一条任务建议这样写：
请先只读分析当前项目。不要修改任何文件。请输出：
1. 项目类型和主要技术栈
2. 入口文件和核心目录
3. 本地启动命令
4. 测试命令
5. 你建议我优先补充到 CLAUDE.md 的项目规则这类任务能帮助 Claude Code 建立上下文，也能让你检查它是否真的读懂了项目，而不是一上来就改代码。
Mac 上的推荐首次工作流
第一步：只读盘点项目
先让 Claude Code 阅读 README、依赖文件、目录结构和测试配置。不要急着让它写功能。你要确认它能说出项目的启动命令、测试命令、主要模块和风险点。
第二步：让它生成修改计划
当你准备修 bug 或加功能时，先要求它输出计划：
请先不要改代码。请根据当前项目结构，给出实现这个功能的修改计划，包括会改哪些文件、每个文件改什么、需要运行哪些验证命令。第三步：小步修改并验证
确认计划后，再让它修改。每次只处理一个清晰任务，修改后运行测试或构建。不要一次把“重构、修 bug、加功能、改样式、升级依赖”全部塞进一个请求。
第四步：提交前做复核
在提交前让 Claude Code 检查 diff：
请 review 当前 git diff，重点看是否有明显 bug、遗漏测试、误改配置、泄露密钥或不必要的大范围重构。这一步适合和人工复核配合使用，不能替代你自己的最终检查。
常见问题排查
问题一：claude: command not found
先重新打开终端，再执行 which claude。如果仍然找不到，检查 Homebrew 路径、shell 配置和安装方式。Apple Silicon Mac 特别要注意 /opt/homebrew/bin 是否在 PATH 中。
问题二：安装脚本执行失败
检查网络、代理、公司防火墙和 TLS 拦截。如果当前网络无法访问安装地址，可以换网络后重试。不要从不明来源下载所谓“离线安装包”。
问题三：Claude Code 看不到项目文件
先确认你是在项目根目录执行 claude。用 pwd、ls 和 git status 检查目录。项目不要放在权限复杂、同步异常或路径包含大量特殊字符的位置。
问题四：权限确认看不懂
把每次确认拆成“要读什么、要改什么、要运行什么”。如果命令涉及删除、覆盖、上传、发布、数据库、密钥、生产环境，先拒绝或让 Claude Code 解释风险。
问题五：Node 项目无法启动
Claude Code 本身不是 Node 运行时。它可以帮你分析和修改 Node 项目，但项目启动仍然依赖你本机的 Node、npm、pnpm 或 yarn。先执行：
node -v
npm -v如果项目需要特定 Node 版本，建议用 nvm 或 fnm 管理版本，并把要求写进 README 或 CLAUDE.md。
安全建议：Mac 本地使用也要保护密钥
不要让 Claude Code 输出密钥
项目中常见的 .env、API Key、数据库密码、OAuth Secret、应用专用密码都不要让 Claude Code 打印到对话里。你可以允许它识别“是否存在配置文件”，但不要让它读取或展示敏感值。
不要直接运行高风险命令
对 rm -rf、数据库清空、线上部署、生产环境迁移、批量覆盖文件等命令保持谨慎。让 Claude Code 先解释命令含义、影响范围和回滚方案，再决定是否执行。
用 Git 保存可回退状态
在让 Claude Code 修改项目之前，先确认工作区状态：
git status如果已有未提交改动，先确认这些改动是谁做的、是否要保留。不要让工具随意覆盖你还没保存的工作。
FAQ
Claude Code 在 Mac 上必须安装 Homebrew 吗？
不必须。你可以使用官方原生安装脚本，也可以使用 Homebrew cask。新手如果已经在用 Homebrew，可以走 Homebrew；如果没有 Homebrew，用官方安装脚本更直接。
Mac 自带 Terminal 能用 Claude Code 吗？
可以。Terminal 已经足够。iTerm2 只是更强的终端工具，不是 Claude Code 的必需条件。
为什么安装后仍然提示 command not found？
常见原因是当前终端会话没有重新加载 PATH、Homebrew 路径没有写入 shell 配置、或者机器上存在多个安装来源。先重开终端，再用 which -a claude 检查路径。
Claude Code 应该从哪个目录启动？
建议从项目根目录启动，也就是包含 README、依赖文件、源码目录和 Git 仓库的目录。不要从桌面、下载目录或上一级大文件夹随意启动。
是否需要给 Claude Code 完全磁盘访问权限？
一般不建议一开始就给过大的系统权限。优先把项目放在普通开发目录，让终端能访问该目录即可。遇到具体权限问题时，再按需要处理。
可以让 Claude Code 自动修改项目吗？
可以，但建议先只读分析，再让它给出修改计划，确认后再执行。涉及删除、部署、数据库、密钥和生产环境的操作要额外谨慎。
CLAUDE.md 有必要写吗？
有必要，尤其是长期项目。它能记录项目约定、测试命令、禁止事项和协作规则，减少每次重新解释上下文的成本。
参考来源
本文安装命令、系统要求和权限相关说明参考 Claude Code 官方文档，包括 Setup、Quickstart、Security、Settings 与 Memory 页面。由于 Claude Code 安装方式可能更新，正式操作前建议再以官方文档为准。
环境配置与 Docker 工作流
适合阅读安装部署、本地配置、服务器搭建和自动化流程类文章后继续转化。
