企业官网建设流程全解析

1. 为什么要在 Mac 上折腾 Claude Code

Claude Code 是 Anthropic 推出的一款命令行 AI 编程助手，它直接跑在终端里，能读写你本地的项目文件、执行 shell 命令、跑测试、改 bug，本质上是一个"住在终端里的结对程序员"。和网页版聊天窗口最大的区别在于：它能看到你真实的代码库结构，能直接动手改文件，而不是只给你一段需要手动复制粘贴的代码片段。

我第一次在 Mac 上装它的时候，踩的坑比想象中多。官方文档写得很简洁，但实际执行时会遇到 Node 版本不对、Homebrew 装到一半卡住、终端权限报错、VSCode 集成找不到入口等一系列问题。更麻烦的是，首次启动会要求登录 Anthropic 账号，而很多人手头并没有可用的账号，或者只是想先在本地跑起来看看效果。这篇内容就是把我自己从零到跑通的完整过程拆开讲清楚，包括怎么绕过首次登录环节、怎么和 VSCode 打通、以及那些文档里不会写的坑。

适合读这篇的人有三类：一是刚拿到 Mac、想体验命令行 AI 编程的新手；二是已经用过网页版 Claude、想把它接进本地工作流的开发者；三是被 Node.js 环境、Homebrew 报错卡住、想找一份能直接抄的安装流程的人。不管你之前有没有用过 CLI 工具，跟着走一遍基本都能跑起来。

需要提前说明的是，Claude Code 本身是一个需要联网调用模型服务的工具，安装和配置过程不涉及任何网络访问的特殊处理，所有操作都在本地终端完成。下面所有步骤都是基于 macOS 常见环境（Intel 和 Apple Silicon 都适用）整理的，遇到差异我会单独标注。

2. 装之前先把环境理清楚

2.1 Node.js 版本是第一个拦路虎

Claude Code 是通过 npm 分发的，所以 Node.js 是硬性依赖。但这里有个坑：不是随便装个 Node 就行。Claude Code 要求 Node.js 18 或更高版本，而且实测下来，Node 18 的某些小版本会出现node:util模块导出报错，具体表现是启动时提示The requested module 'node:util' does not provide an export named。这个报错在 Node 18.0 到 18.12 之间比较常见，原因是这些版本对 ESM 模块的支持还不完整。

我的建议是直接上 Node 20 LTS 或 Node 22 LTS，跳过 18 这个坑。如果你已经装了 18 且遇到报错，不用卸载重装，用 nvm 切一个版本就行。

先检查当前版本：

node -v npm -v

如果版本低于 18，或者你想多版本共存，推荐用 nvm 管理。装 nvm 的方式有两种，一种是官方脚本，一种是 Homebrew。我倾向官方脚本，因为它不依赖 Homebrew，出问题概率低：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

装完之后要重新加载 shell 配置。如果你用的是 zsh（macOS 默认），执行：

source ~/.zshrc

然后装 Node 20：

nvm install 20 nvm use 20 nvm alias default 20

最后一行是把 20 设为默认版本，这样新开终端不用每次手动切。验证一下：

node -v # 应该输出 v20.x.x

注意：如果你之前用 Homebrew 装过 Node，nvm 和它可能会打架。表现是which node指向/opt/homebrew/bin/node而不是 nvm 的路径。解决办法是把 Homebrew 版的 Node 卸载掉：brew uninstall node，然后重开终端让 nvm 接管。

2.2 Homebrew 报错别慌，先看错误类型

Homebrew 是 Mac 上装命令行工具最省事的方式，但国内网络环境下它经常卡在Updating Homebrew或者下载 bottle 超时。常见的报错有三类：

第一类是Failed to download，通常是网络问题，重试或者换个时间段就行。第二类是Permission denied，一般出现在/usr/local或/opt/homebrew目录权限不对的时候，需要手动改权限。第三类是Xcode Command Line Tools没装，报错信息里会明确提示。

先确认 Homebrew 本身在不在：

brew --version

如果提示command not found，说明没装。安装命令是：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Silicon 机器装完后需要手动把 brew 加进 PATH，安装脚本最后会提示你执行两行命令，类似：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc eval "$(/opt/homebrew/bin/brew shellenv)"

Intel 机器的路径是/usr/local/bin/brew，脚本会自动处理。装完再跑一次brew --version确认。

如果卡在更新环节，可以临时跳过自动更新：

export HOMEBREW_NO_AUTO_UPDATE=1

这行可以写进~/.zshrc，省得每次装东西都等更新。不过要注意，长期跳过更新可能导致某些 formula 版本过旧，偶尔手动brew update一次就行。

2.3 终端选择：系统自带够用，但 iTerm2 更顺手

macOS 自带的 Terminal.app 完全能跑 Claude Code，但如果你打算长期用命令行工具，iTerm2 的体验会好很多，比如分屏、搜索、粘贴历史这些功能。装它一条命令：

brew install --cask iterm2

不装也完全没问题，这不是必须项。我提这一嘴是因为后面配置 VSCode 集成时，终端的选择会影响一些快捷键行为，提前知道有这回事就行。

3. 安装 Claude Code 的完整流程

3.1 用 npm 全局安装

环境准备好之后，安装本身只有一条命令：

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

-g是全局安装，装完之后在任何目录都能直接敲claude调用。如果你不想全局装，也可以只在某个项目里局部装，但那样每次都要用npx调用，比较麻烦，不推荐。

安装过程中如果卡住不动，大概率是 npm 源的问题。可以临时换成国内镜像：

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

装完再换回来：

npm config set registry https://registry.npmjs.org

验证安装是否成功：

claude --version

能输出版本号就说明装好了。如果提示command not found，检查一下 npm 的全局 bin 目录在不在 PATH 里：

npm config get prefix

正常应该输出类似/Users/你的用户名/.nvm/versions/node/v20.x.x。如果这个路径不在 PATH 里，需要手动加：

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc source ~/.zshrc

3.2 首次启动与跳过登录的思路

直接敲claude启动，第一次会引导你登录 Anthropic 账号。如果你有账号，跟着提示走浏览器授权就行。如果没有，或者不想登录，可以走另一条路：通过环境变量指定第三方兼容的 API 端点。

这里要说明原理：Claude Code 本质上是一个客户端，它把对话请求发到一个兼容 Anthropic API 格式的服务端。官方默认指向 Anthropic 自己的服务，但你可以通过ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量把它指向任何兼容的服务。

具体操作是，在~/.zshrc里加两行：

export ANTHROPIC_BASE_URL="你的服务地址" export ANTHROPIC_API_KEY="你的密钥"

然后source ~/.zshrc生效。再启动claude时，它就不会再弹登录引导，而是直接用你配置的端点。

注意：这两个变量的值需要你自己准备好，我在这里不提供任何具体服务地址。配置之前确认你的服务端兼容 Anthropic 的 Messages API 格式，否则会出现请求格式错误。

如果你只是想先看看界面长什么样，也可以在启动时加--help参数，它不会触发登录：

claude --help

这能让你确认命令本身是正常工作的。

3.3 配置文件放在哪，怎么改

Claude Code 的配置分两层：全局配置在~/.claude/目录下，项目级配置在项目根目录的.claude/里。全局配置主要放 API 相关的设置，项目级配置放权限规则、忽略文件等。

查看全局配置目录：

ls -la ~/.claude/

里面常见的文件有settings.json（主配置）、credentials.json（凭证，如果走登录流程的话）。如果你用环境变量方式，credentials.json可能不存在，这是正常的。

项目级配置我建议每个项目单独设，因为不同项目对文件读写的权限要求不一样。在项目根目录建一个.claude/settings.json，可以控制哪些命令允许自动执行、哪些文件不允许读取。这个后面讲权限的时候再展开。

4. 和 VSCode 打通：终端与编辑器的配合

4.1 为什么要在 VSCode 里用 Claude Code

Claude Code 是 CLI 工具，理论上不需要编辑器也能用。但在 VSCode 里用它有几个实际好处：一是终端就在编辑器底部，改完代码不用切窗口；二是 VSCode 的文件树能让你快速确认 Claude 改了哪些文件；三是配合 VSCode 的 diff 视图，能直观看到每次修改的前后对比。

VSCode 本身装起来很简单，官网下载 dmg 拖进 Applications 就行，或者用 Homebrew：

brew install --cask visual-studio-code

装完第一次打开，建议先装几个基础插件：中文语言包（如果你需要）、Python 或 C/C++ 扩展（看你写什么语言）。这些不是 Claude Code 的依赖，但能让整个开发环境更完整。

4.2 在 VSCode 终端里调用 Claude Code

VSCode 内置终端默认会用系统的 shell，也就是 zsh。只要你在系统终端里能跑claude，在 VSCode 终端里也能跑。打开方式是按Ctrl+`（反引号），或者菜单里选 Terminal > New Terminal。

有一个细节：VSCode 终端启动时加载的是登录 shell 还是非登录 shell，会影响~/.zshrc里的环境变量是否生效。如果发现 VSCode 终端里claude找不到，或者 API 环境变量没生效，检查 VSCode 设置里的terminal.integrated.inheritEnv选项，确保它是开启的。

另一个常见需求是让 Claude Code 在 VSCode 里以分屏方式常驻。可以装一个叫 "Terminal Tabs" 或者直接用 VSCode 自带的分屏功能（Cmd+\）把终端拆到右侧，左边写代码右边对话，效率会高不少。

4.3 用 tasks.json 一键启动

如果你不想每次手动敲claude，可以在项目里配一个 VSCode task。在.vscode/tasks.json里加：

{ "version": "2.0.0", "tasks": [ { "label": "Start Claude Code", "type": "shell", "command": "claude", "presentation": { "reveal": "always", "panel": "dedicated" }, "problemMatcher": [] } ] }

配好之后按Cmd+Shift+P，输入Run Task，选 "Start Claude Code"，它就会在一个专用终端面板里启动。这个配置的好处是终端面板是独立的，不会和你手动开的终端混在一起。

5. 实际使用中的核心操作与技巧

5.1 基本对话与文件操作

启动claude之后，你会看到一个交互式提示符。直接输入自然语言就行，比如"帮我看一下这个项目的目录结构"或者"src/utils.js 里那个函数有什么问题"。它会自己决定要不要读文件、读哪些文件。

几个我常用的操作模式：

第一种是让它先探索再动手。比如新接手一个项目，我会说"先读一下 README 和 package.json，告诉我这个项目是干什么的，用了哪些主要依赖"。它会自动读取相关文件并总结，比我自己翻快很多。

第二种是限定范围的修改。比如"只改 src/api/client.js 里的超时时间，从 5 秒改成 10 秒，别动其他文件"。明确限定范围能减少它误改无关代码的概率。

第三种是让它跑命令验证。比如"改完之后跑一下 npm test，看看有没有挂"。它会执行测试命令并把结果读回来，如果挂了还会尝试分析原因。

注意：Claude Code 执行 shell 命令前会询问你是否允许。第一次遇到某个命令时，它会问"是否允许执行 xxx"，你可以选择允许一次、允许这个命令、或者拒绝。建议对rm、git push这类有副作用的命令保持手动确认，别图省事全放行。

5.2 权限配置：哪些能自动跑，哪些必须问

Claude Code 的权限系统是它安全性的核心。默认情况下，读文件一般不需要确认，写文件和执行命令需要确认。你可以在项目级.claude/settings.json里细化规则。

一个典型的配置长这样：

{ "permissions": { "allow": [ "Read", "Bash(npm test)", "Bash(npm run lint)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push *)" ] } }

allow列表里的操作不会弹确认，deny列表里的直接禁止。我一般会把测试和 lint 命令放进 allow，把删除和推送放进 deny。这样日常开发时它跑测试不用我反复点确认，但危险操作它碰不了。

这个配置的粒度可以很细，比如Bash(git commit *)允许提交但不允许推送，Read(src/**)只允许读 src 目录。具体语法参考官方文档，但核心思路就是：高频低危的放 allow，低频高危的放 deny。

5.3 上下文管理：别让它读太多无关文件

Claude Code 每次对话都会把相关文件内容塞进上下文，上下文越长，响应越慢，成本也越高。所以有两个习惯值得养成：

一是用.claudeignore文件排除无关目录。语法和.gitignore一样，把node_modules/、dist/、*.log这些加进去，它就不会去读。这个文件放在项目根目录。

二是对话时明确指定文件路径。与其说"看看这个项目哪里有问题"，不如说"检查 src/components/Header.jsx 和它的测试文件"。范围越明确，它读的文件越少，回答也越聚焦。

如果对话变长了，感觉它开始"忘事"或者答非所问，可以用/clear命令清空当前会话上下文，重新开始。这个命令在交互模式里直接输入就行。

6. 常见问题与排查实录

6.1 安装阶段的典型报错

6.2 启动阶段的典型问题

启动时卡在登录页面出不来，是最常见的问题。如果你已经配了环境变量但还是弹登录，检查两点：一是环境变量是否真的生效了（在终端里echo $ANTHROPIC_BASE_URL看看有没有值），二是变量名有没有拼错。这两个变量名是大小写敏感的。

另一个问题是启动后提示 API 请求失败。这种情况先确认你的服务端点是否可达，可以用 curl 简单测一下：

curl -I $ANTHROPIC_BASE_URL

如果返回 404 或 502，说明地址不对或者服务没起来。如果返回 401，说明密钥有问题。

6.3 使用阶段的效率问题

响应慢是最影响体验的问题。除了上下文过长之外，还有一个原因是模型本身在思考复杂问题时需要时间。我的经验是，把大任务拆成小步骤，一步一步来，比一次性丢一个大需求要快得多。比如不要问"帮我重构整个项目"，而是"先看 src/utils/date.js，把里面的日期格式化函数改成用 dayjs"。

还有一个坑是它有时候会"过度热情"，你没让它改的文件它也动了。避免方法是每次对话开头明确说"只改我指定的文件"。如果它已经改了不该改的，用git diff看改动，git checkout回滚单个文件。

6.4 卸载与清理

如果哪天不想用了，卸载很简单：

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

配置目录~/.claude/不会自动删，需要手动清理：

rm -rf ~/.claude

项目级的.claude/目录同理，看你还需不需要保留权限配置。Mac 上清理系统数据时，这些目录也值得顺手看一眼，有时候日志文件会攒到几百兆。

7. 我踩过的几个坑和对应心得

第一个坑是 Node 版本。我一开始图省事用 Homebrew 装了 Node，结果版本是 18 的某个早期版本，启动就报node:util那个错。折腾了半天才意识到是版本问题，换成 nvm 装 Node 20 之后一次通过。所以现在我的习惯是：Mac 上永远用 nvm 管 Node，不用 Homebrew 装。

第二个坑是环境变量没生效。我在~/.zshrc里加了变量，但 VSCode 终端里就是不认。后来发现是 VSCode 启动方式的问题，从 Dock 启动的 VSCode 不会加载登录 shell 的环境变量。解决办法是从终端里用code .命令启动 VSCode，这样它继承的环境变量就是完整的。

第三个坑是权限放太宽。有次我图省事把所有 Bash 命令都设成 allow，结果它跑了一个我没预期的git checkout .，把我没提交的改动全冲掉了。从那以后我的原则是：写操作和 git 操作永远手动确认，只把只读命令和测试命令放 allow。

第四个坑是上下文污染。有次我在一个对话里先让它改 A 文件，又让它改 B 文件，再回头问 A 的问题，它已经记混了。后来我养成习惯：一个任务一个会话，做完就/clear，需要跨文件操作时再重新说明背景。这样虽然多打几个字，但准确率高很多。

这些经验说起来都是小事，但真卡住的时候挺耽误时间的。希望这份流程能让你少走点弯路，把时间花在写代码上而不是配环境上。