从零开始：用 ZCF 把 Claude Code 环境一次配好

本文面向已经熟悉命令行、准备把 Claude Code 用在实际项目中的开发者。读完你可以 5 分钟跑完初始化，并拥有可复用的中文/英文双语工作流。

1. 为什么需要 ZCF？

Claude Code 本身没有图形界面，配置文件散落在 ~/.claude/ 目录。
第一次用的时候，你可能会遇到：

  • •
    不知道哪些文件该放哪
  • •
    每次换电脑就要重新写配置
  • •
    MCP 服务（例如浏览器控制、文档搜索）手动配置容易出错

ZCF（Zero-Config Claude-Code Flow）把上述步骤压缩成一条命令，同时保留“想改随时改”的灵活性。

2. 两条命令，覆盖 90% 场景

你现在的状态 终端输入 会发生什么
从没装过 Claude Code npx zcf 安装 → 选语言 → 配置 API → 选 MCP → 生成全套文件
已经装过，只想要工作流 npx zcf u 仅更新 CLAUDE.md、agents、commands 三个目录，旧配置自动备份

小提示：
u 是 update 的缩写，相当于“增量更新”，不会动你的 API Key 和 MCP 设置。

3. 初始化全过程拆解（带截图位置）

下面用中文界面演示一次完整流程。你在终端看到的内容与下文一致，可直接对照操作。

步骤 1：选择脚本语言

? Select script language / 选择脚本语言:
  ❯ 简体中文
    English

这一步只影响安装脚本的提示语言，对最终配置文件语言没有影响。

步骤 2：选择配置文件语言

? 选择 Claude Code 配置语言:
  ❯ 简体中文 (zh-CN)
    English (en)
  • •
    选 zh-CN：后续生成的 CLAUDE.md、自定义命令注释都是中文，阅读门槛低。
  • •
    选 en：token 占用更低，适合英文团队。

步骤 3：自动安装 Claude Code

如果系统检测不到 claude 命令，会提示：

? 检测到 Claude Code 未安装，是否自动安装？(Y/n)

按回车即可，ZCF 会调用 npm 全局安装，兼容 Win / macOS / Linux。

图：安装成功提示
install-success

步骤 4：配置 API

你有两条路：

  1. 立即配置 – 输入 https://api.anthropic.com 和你的 sk-***
  2. 稍后配置 – 跳过，之后用 claude 命令的交互登录也行

步骤 5：处理旧配置

如果 ~/.claude/ 已经存在：

? 检测到已有配置文件，如何处理？
  ❯ 备份并覆盖全部
    仅更新工作流相关并备份旧配置
    合并配置
    跳过
  • •
    备份并覆盖全部：旧文件移到 ~/.claude/backup/时间戳/，新手推荐。
  • •
    仅更新工作流：相当于 zcf u，保留 API 与 MCP。
  • •
    合并：同名 key 会被新值覆盖，其余保留。
  • •
    跳过：完全不动现有文件，仅当“看看会发生什么”时使用。

步骤 6：选择 MCP 服务

? 选择要安装的 MCP 服务（空格选择，回车确认）
  ❯ ◯ 全部安装
    ◯ Context7 文档查询
    ◯ DeepWiki
    ◯ Playwright 浏览器控制
    ◯ Exa AI 搜索

每项服务后面都有简短说明。不确定就全选，事后可在 ~/.claude/settings.json 里开关。

步骤 7：输入 MCP 所需的 API Key（如 Exa）

如果上一步勾选了 Exa，ZCF 会立即询问：

? 请输入 Exa API Key（可从 https://dashboard.exa.ai/api-keys 获取）

复制粘贴即可。
完成后看到：

🎉 配置完成！使用 'claude' 命令开始体验。

4. 目录结构速览

装完以后，~/.claude/ 长成这样：

~/.claude/
├── CLAUDE.md          # 系统指令，告诉 AI 如何写代码
├── settings.json      # API 地址、模型、权限开关
├── agents/            # 预置的 planner、ui-ux-designer 代理
├── commands/          # 自定义 /feat、/workflow 等命令
└── backup/            # 每次更新自动保存的旧文件

项目根目录还会出现 .claude/（注意前面有个点），用于存放该项目的计划、设计稿等临时文档。
建议把 .claude/ 写进 .gitignore，避免提交无关变更。

5. 命令行参数速查表

完整写法 缩写 作用
zcf — 进入交互式初始化
zcf update zcf u 增量更新 Prompt 和命令
zcf --config-lang zh-CN zcf -c zh-CN 强制用中文模板
zcf --force zcf -f 覆盖现有配置
zcf --help zcf -h 查看所有选项
zcf --version zcf -v 查看当前版本

6. 常见疑问（FAQ）

Q1：我已经用 Cursor / Copilot，还需要 Claude Code 吗？

A：它们解决的问题不同。Cursor 更像 IDE；Claude Code 是“终端里的结对程序员”。ZCF 只是帮你把 Claude Code 装好、配好，不冲突。

Q2：公司电脑不能全局安装 npm 包怎么办？

A：ZCF 本质是 npm 包，可以 npx zcf 一条命令运行，无需管理员权限。也可以把 ~/.claude/ 整个目录拷到另一台机器，直接复用。

Q3：如何卸载？

A：

  1. 删除全局包：npm uninstall -g @anthropic-ai/claude-code
  2. 删除配置：rm -rf ~/.claude/
  3. 项目目录里的 .claude/ 如不再需要也可删。

Q4：想临时关闭某个 MCP 服务？

A：编辑 ~/.claude/settings.json，把对应服务的 "enabled": true 改成 false，保存后重启 claude 即可。

7. 三分钟上手第一条任务

配置完成后，在项目根目录执行：

claude

进入 Claude Code 交互界面，先输入：

/init

它会在 .claude/ 里生成一份项目简介，方便 AI 理解目录结构。

接着可以试试：

/feat 添加用户登录页面

AI 会分两步走：

  1. plan 阶段 – 输出需求拆分、文件变更列表
  2. ui 阶段 – 给出 React 组件、样式、测试代码

每一步都会停下来等你确认，完全掌控。

8. 进阶：把 ZCF 集成到 CI

如果你的团队需要在 Docker 镜像里预装 Claude Code，只需在 Dockerfile 加两行：

RUN npm install -g @anthropic-ai/claude-code
COPY .claude/ /root/.claude/

这样镜像启动后就能直接 claude 命令跑脚本，无需再次交互。

9. 故障排查清单

现象 可能原因 解决
claude: command not found 环境变量未刷新 重开终端或 source ~/.zshrc
MCP 服务报错 401 API Key 填错 重新运行 zcf，选择“合并配置”
配置文件冲突 多人共用一台电脑 把 ~/.claude/ 加入版本管理忽略，每人用自己的目录

10. 小结

ZCF 把“装好 Claude Code → 配好 API → 装好常用工具 → 生成项目模板”浓缩成一条命令，同时留下完全可读的 Markdown 文件，方便日后手动调整。
如果你已经熟悉命令行，5 分钟即可拥有：

  • •
    中文或英文的系统指令
  • •
    自动备份的旧配置
  • •
    一键启停的 MCP 服务
  • •
    /feat、/workflow 等开箱即用的开发流程

下一步？打开终端，输入：

npx zcf

亲手跑一次，你会发现配置 Claude Code 原来可以这么简单。