用了一年多 Claude Code，我有个发现：用 VS Code 插件的人，大概只用到了 Claude Code 能力的一半。

另一半在 CLI 里。

插件模式适合"交互式"的工作——你在编辑器里写代码，遇到问题随手问 Claude。CLI 模式适合"批处理式"的工作——你需要对一批文件做同样的操作，或者把 Claude 嵌入自动化流程，或者在没有 GUI 的服务器环境里使用。

这两个模式不是替代关系，是互补关系。但 CLI 模式明显被低估了——它能做的事情，很多人根本没想到。

为什么 CLI 模式值得单独学

我是被一个具体的场景逼着去研究 CLI 的。

有一次我的出海项目做了一次大规模重构，把所有的 API 错误返回格式统一改了。问题是项目里有 23 个 API 路由文件，每个都要改。

用插件模式，我需要：打开文件 → 触发 Claude → 输入 Prompt → 接受修改 → 下一个文件，循环 23 次。算了一下，就算每个文件花 3 分钟，23 个文件就是 70 分钟。

用 CLI，我写了一个 shell 脚本，把所有路由文件路径传给 Claude，统一处理，20 分钟全部搞定，还顺手生成了改动日志。

CLI 的本质优势：可编程、可批处理、可集成进任何工作流。

第一步：安装和验证

如果你只装了 VS Code 插件，没有装 CLI，先补上：

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

验证安装：

claude --version

验证 API Key 配置：

claude -p "用一句话介绍你自己"

如果返回了正常的回答，说明 CLI 已经连接到你的 API Key，可以开始用了。

这里有个细节要注意： CLI 和 VS Code 插件共享同一个 API Key 配置。如果你之前在插件里配过 Key，CLI 会自动读取，不需要重新配。但如果你用的是自定义端点（比如通义千问），需要单独在 CLI 里配置环境变量：

export ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export ANTHROPIC_API_KEY=sk-你的key

第二步：基础用法——从简单指令开始

最基础的用法：-p 单次对话

claude -p "解释一下 React 的 useCallback 和 useMemo 的区别，100字以内"

-p 是 --print 的缩写，表示"执行这个 Prompt，输出结果，然后退出"。不进入交互模式，适合脚本调用。

说人话就是： -p 就是"帮我做这一件事，做完就走"。

把文件内容传给 Claude：管道操作

cat src/lib/utils.ts | claude -p "找出这个文件里所有可能的运行时错误，列出来"

用管道（|）把文件内容传给 Claude，它就能直接分析。

更实用的写法是用文件重定向：

claude -p "Review 这段代码，找出类型不安全的地方" < src/api/payment.ts

这里有个细节要注意： 管道传入的内容会被 Claude 当作"上下文"，你的 -p 指令是对这个上下文的操作。所以 Prompt 要写"对这段内容做什么"，而不是"帮我找一个文件"。

输出结果写入文件：重定向输出

claude -p "为这个函数写 JSDoc 注释" < src/utils/formatCurrency.ts > output.ts

把 Claude 的输出重定向到文件。不过我更常用的是结合 --output-format 参数控制输出格式。

第三步：进阶用法——真正提升效率的地方

批量处理文件：用 find + xargs

这是我用 CLI 最多的场景。把一批文件批量交给 Claude 处理：

下面这个脚本把项目里所有 API 路由文件统一加上请求日志：

#!/bin/bash
# add-request-logging.sh
# 为所有 API 路由文件加上请求日志

find app/api -name "route.ts" | while read file; do
  echo "处理: $file"
  claude -p "
在这个 Next.js API 路由文件里加上请求日志：
- 在每个 handler 函数开头加 console.log，格式：[METHOD] /path - timestamp
- timestamp 用 UTC 格式：new Date().toISOString()
- 不要改动其他逻辑
输出完整的修改后文件内容，不要加任何解释。
" < "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
  echo "完成: $file"
done

echo "全部处理完毕"

说人话就是： 这个脚本找到所有 route.ts 文件，逐个传给 Claude 处理，把输出结果覆盖原文件。你只需要跑一次命令，23 个文件全搞定。

这里有个细节要注意： 先输出到 .tmp 文件再 mv 覆盖，而不是直接 > "$file"，是为了防止 Claude 处理失败时把原文件清空。这个细节我吃过亏，直接重定向的话，如果 API 调用失败，原文件就变成空文件了。

结构化输出：--output-format json

当你需要把 Claude 的输出用于后续程序处理时，用 JSON 格式输出：

claude -p "
分析这个文件，返回 JSON 格式：
{
  \"functions\": [函数名列表],
  \"exports\": [导出名列表],
  \"dependencies\": [import 的依赖列表],
  \"hasTests\": boolean
}
只返回 JSON，不要其他内容。
" --output-format json < src/lib/stripe.ts

然后在 shell 脚本里用 jq 解析：

result=$(claude -p "..." --output-format json < src/lib/stripe.ts)
functions=$(echo $result | jq -r '.functions[]')
echo "发现以下函数：$functions"

大多数教程不告诉你的细节： --output-format json 并不是让 Claude 输出 JSON 的唯一方式，但它会对输出做一层包装，确保结果是合法的 JSON 字符串，不会出现特殊字符导致解析失败的问题。如果只是在 Prompt 里说"输出 JSON"，偶尔会有格式问题。

交互模式：--interactive

不加 -p，直接运行 claude，进入交互模式——和 VS Code 插件的对话体验类似，但在终端里：

claude --interactive

适合在服务器上临时调试，或者在不方便打开编辑器的场景下用。

我在部署脚本出问题时，会直接在服务器上进交互模式让 Claude 帮我排查——比本地 SSH 过来再打开编辑器快多了。

设置系统提示词：--system

给整个 CLI 会话设置一个系统级提示词：

claude --system "你是一个专注于出海 Web 开发的 TypeScript 工程师，所有代码必须符合以下规范：金额用整数（分为单位），时间用 UTC，多语言用 i18n key" -p "写一个获取用户订单列表的 API 路由"

说人话就是： --system 相当于临时的 CLAUDE.md，不会永久保存，只对当次命令有效。适合在脚本里临时注入项目规范，不需要修改项目配置文件。

第四步：实战脚本工具集

这些脚本我在出海项目里真实在用，直接复制放到项目根目录的 scripts/claude/ 目录下。

脚本一：批量 Code Review

#!/bin/bash
# scripts/claude/review.sh
# 用法：./scripts/claude/review.sh [文件路径]
# 示例：./scripts/claude/review.sh src/app/api/payment/route.ts

FILE=${1:-""}

if [ -z "$FILE" ]; then
  echo "用法: $0 <文件路径>"
  exit 1
fi

if [ ! -f "$FILE" ]; then
  echo "文件不存在: $FILE"
  exit 1
fi

echo "🔍 正在 Review: $FILE"
echo "================================"

claude -p "
对这个文件做专业的 Code Review，重点检查以下方面：

1. **类型安全**：有没有 any、类型断言滥用、可能的 null/undefined 问题
2. **出海场景**：时区处理是否正确、金额是否用整数、字符串是否有编码问题
3. **安全性**：有没有 SQL 注入风险、XSS 风险、敏感信息泄漏
4. **性能**：有没有 N+1 查询、不必要的全量加载、缺少分页
5. **错误处理**：所有异步操作是否有 try-catch、错误是否有合理的用户提示

对每个问题说明：问题在第几行、严重程度（高/中/低）、建议怎么修复。
如果没有问题就说「本文件 Review 通过」。
" < "$FILE"

脚本二：自动生成 i18n 文案

#!/bin/bash
# scripts/claude/gen-i18n.sh
# 用法：./scripts/claude/gen-i18n.sh "功能名称" "key前缀"
# 示例：./scripts/claude/gen-i18n.sh "用户设置页" "settings.profile"

FEATURE=${1:-"新功能"}
PREFIX=${2:-"feature"}

claude -p "
为「${FEATURE}」功能生成完整的 i18n 文案，key 前缀为 \"${PREFIX}\"。

需要包含以下类型的文案：
- 页面标题、小节标题
- 表单标签、占位符、帮助文字
- 按钮文字（保存、取消、确认、删除等）
- 成功/失败/警告提示
- 空状态文案

输出两个 JSON 对象，格式如下，直接输出不要其他内容：

英文版（en.json 片段）：
{JSON}

中文版（zh.json 片段）：
{JSON}
"

脚本三：生成迁移前的影响分析

#!/bin/bash
# scripts/claude/migration-impact.sh
# 在执行数据库迁移前，分析影响范围
# 用法：./scripts/claude/migration-impact.sh prisma/migrations/最新迁移文件.sql

MIGRATION_FILE=${1:-""}

if [ -z "$MIGRATION_FILE" ]; then
  # 自动找最新的迁移文件
  MIGRATION_FILE=$(find prisma/migrations -name "*.sql" | sort | tail -1)
fi

echo "📊 分析迁移影响范围：$MIGRATION_FILE"

claude -p "
分析这个数据库迁移 SQL，评估影响范围：

1. **破坏性变更**：有没有删列、改类型、加非空约束等可能导致数据丢失的操作
2. **影响的 API**：根据表名推断哪些 API 路由可能需要同步修改
3. **迁移风险**：生产环境执行这个迁移有什么风险，需要停服吗
4. **回滚方案**：如果迁移失败，如何回滚

用表格输出「影响的表」和「影响级别」，然后用文字描述建议的操作步骤。
" < "$MIGRATION_FILE"

踩坑环节

坑一：脚本处理大文件时 API 超时

我有个脚本批量处理项目里的所有组件文件，加上 TypeScript 类型检查。跑到第 8 个文件的时候，脚本突然挂死了，半天没有响应。

我发现的方式： 等了 5 分钟，手动 Ctrl+C 终止，看到一个超时错误。那个文件是个特别大的表单组件，有 600 多行。

怎么解决的： 加了两个保险机制：

# 1. 加超时限制，超过 60 秒就跳过
timeout 60 claude -p "..." < "$file" || echo "⚠️ 跳过（超时）：$file"

# 2. 大文件先截取前 200 行分析
if [ $(wc -l < "$file") -gt 300 ]; then
  echo "文件较大，只分析前 200 行"
  head -200 "$file" | claude -p "..."
else
  claude -p "..." < "$file"
fi

坑二：并行处理导致 API 限流

觉得串行太慢，改成并行处理——用 & 让多个 Claude 进程同时跑：

# 这样写会触发限流
find app/api -name "route.ts" | while read file; do
  claude -p "..." < "$file" &  # 同时启动多个进程
done
wait

结果跑了没几秒，开始大量报 Rate limit exceeded，一半文件没处理完。

我发现的方式： 终端里一堆红色的错误信息，看日志发现是 429 错误。

怎么解决的： 改成限速的并行，用 xargs -P 控制最大并发数，同时加请求间隔：

find app/api -name "route.ts" | xargs -P 3 -I {} bash -c '
  sleep $((RANDOM % 3))  # 随机延迟 0-2 秒，错开请求
  claude -p "..." < "{}"
'

-P 3 表示最多同时 3 个进程，加上随机延迟，基本不会再触发限流。

CLI 模式是 Claude Code 被严重低估的一半。 插件模式让你和 AI 对话，CLI 模式让 AI 融进你的工程流水线。两个都会用，才是真正意义上的 AI 辅助开发。

---

你现在有没有什么重复性的开发工作——每次都要做，每次都一样，就是懒得自动化？

说出来，我帮你想想用 Claude Code CLI 能不能一条命令搞定。