google-zx-scripting

Google ZX 脚本

在使用 Google 的 zx 库编写脚本时，请使用此技能。该工具让你能够高效、安全地使用 JavaScript/TypeScript 编写 Shell 脚本。只阅读任务所需的参考文件。

快速开始

所有 zx 脚本都使用 lite 入口，以确保可移植性。脚本是独立的 .mjs 文件，无需设置项目。

#!/usr/bin/env npx zx

import { $, fs, path, glob, chalk } from 'zx/core';

const files = await glob('src/**/*.ts');
await $`eslint ${files}`;

直接运行：

chmod +x script.mjs && ./script.mjs
# or
npx zx script.mjs

关键规则

1. 始终使用 zx/core — 不要直接使用 zx。这样可以避免使用臃肿的 CLI 封装。
2. 模板字面量会自动转义 — $`echo ${userInput}` 是安全的。绝不要手动给插值变量加引号。
3. 数组会正确展开 — $`cmd ${arrayOfArgs}` 会将每个元素展开为单独的带引号参数。
4. 非零退出码会抛出异常 — 如果预期命令会失败（例如 grep 未匹配到内容），请使用 .nothrow() 来抑制异常。
5. 使用 within() 实现隔离 — 它会创建一个拥有独立 $.cwd 和 $.env 的异步作用域。并行任务必不可少。
6. 使用 .pipe() 管道连接 — 使用 $`cmd1`.pipe($`cmd2`)，而不是 Shell 的 |。
7. 优先使用 zx 内置工具 — 使用 glob() 而不是 find，使用 fs 而不是 cat/cp/mv，使用 fetch() 而不是 curl。
8. cd() 是全局操作 — 使用 within() 或 $({cwd: '/path'}) 来限定目录变更的作用域。
9. 脚本必须是 .mjs 文件 — 这样无需配置打包工具即可支持顶层 await。

参考文件索引

需求	文件
$、ProcessPromise、ProcessOutput、配置、管道、流	references/core-api.md
临时脚本、CLI 工具、构建脚本、部署、项目脚手架	references/scripting-patterns.md
文件处理、数据管道、批量操作、AI 脚本、日志分析	references/processing-recipes.md

任务路由

• 编写快速的一次性命令或 Shell 自动化脚本 -> references/scripting-patterns.md
• 构建构建／部署／CI 脚本 -> references/scripting-patterns.md
• 处理文件、数据、日志或批量操作 -> references/processing-recipes.md
• 需要了解 $、管道、流、配置的 API 细节 -> references/core-api.md
• 组合多种模式（例如构建 + 处理）-> 阅读两个相关文件

导入速查表

// 核心 — 始终从这里开始
import { $, fs, path, glob, chalk } from 'zx/core';

// 其他工具（按需单独导入）
import { spinner, retry, question, echo, sleep, within,
         stdin, tmpdir, tmpfile, which, ps, kill,
         quote, YAML, argv, fetch } from 'zx/core';

验证检查点

在执行破坏性操作或批量操作之前，务必确认操作范围：

// 批量处理前，先确认 glob 的匹配结果
const files = await glob('src/**/*.ts');
console.log(`Found ${files.length} files`);
if (files.length === 0) throw new Error('No files matched — check glob pattern');
if (files.length > 500) throw new Error(`Too many files (${files.length}) — narrow the glob`);

// 为破坏性操作设置试运行标记
const dryRun = argv['dry-run'] ?? false;
for (const file of files) {
    if (dryRun) { console.log(`[dry-run] would delete ${file}`); continue; }
    await fs.rm(file);
}

对于并行操作，请使用 Promise.allSettled() 处理部分失败：

const results = await Promise.allSettled(
    files.map(f => within(async () => $`process ${f}`))
);
const failed = results.filter(r => r.status === 'rejected');
if (failed.length > 0) {
    console.error(chalk.red(`${failed.length}/${results.length} tasks failed`));
    failed.forEach(r => console.error(r.reason));
    process.exitCode = 1;
}

生成脚本的约定

1. Shebang 行：始终将 #!/usr/bin/env npx zx 作为第一行
2. 关闭详细输出：在主要逻辑之前设置 $.verbose = false，以抑制命令回显
3. 错误处理：使用 main().catch() 模式——将逻辑封装在 async function main() 中，然后调用 main().catch(err => { console.error(chalk.red(err.message)); process.exit(1); })
4. 输出颜色：使用 chalk.green() 表示成功，使用 chalk.red() 表示错误，使用 chalk.yellow() 表示警告，使用 chalk.dim() 表示次要信息
5. 进度：在交互场景中，对长时间运行的操作使用 spinner()
6. 参数：使用 argv（预解析的 minimist）处理 CLI 参数
7. 临时文件：使用 tmpdir() 和 tmpfile()——它们会在退出时自动清理
8. 并行处理：对于需要隔离的并行操作，使用带有 within() 的 Promise.all()