入门

¥Getting Started

概述

¥Overview

#!/usr/bin/env zx

await $`cat package.json | grep name`

const branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`

await Promise.all([
  $`sleep 1; echo 1`,
  $`sleep 2; echo 2`,
  $`sleep 3; echo 3`,
])

const name = 'foo bar'
await $`mkdir /tmp/${name}`

Bash 很棒，但在编写更复杂的脚本时，许多人更喜欢更方便的编程语言。JavaScript 是一个完美的选择，但是 Node.js 标准库在使用之前需要额外的麻烦。zx 包为 child_process 提供了有用的封装器，转义参数并提供合理的默认值。

¥Bash is great, but when it comes to writing more complex scripts, many people prefer a more convenient programming language. JavaScript is a perfect choice, but the Node.js standard library requires additional hassle before using. The zx package provides useful wrappers around child_process, escapes arguments and gives sensible defaults.

安装

¥Install

node

npm install zx

bun

bun install zx

deno

deno install -A npm:zx

brew

brew install zx

用法

¥Usage

将脚本写入具有 .mjs 扩展名的文件中，以便在顶层使用 await。如果你更喜欢 .js 扩展，请将脚本封装在 void async function () {...}() 之类的内容中。

¥Write your scripts in a file with an .mjs extension in order to use await at the top level. If you prefer the .js extension, wrap your scripts in something like void async function () {...}().

将以下 shebang 添加到 zx 脚本的开头：

¥Add the following shebang to the beginning of your zx scripts:

#!/usr/bin/env zx

现在你将能够像这样运行脚本：

¥Now you will be able to run your script like so:

chmod +x ./script.mjs
./script.mjs

或通过 CLI：

¥Or via the CLI:

zx ./script.mjs

所有功能（$、cd、fetch 等）均可直接使用，无需任何导入。

¥All functions ($, cd, fetch, etc) are available straight away without any imports.

或者显式导入全局变量（以便在 VS Code 中更好地自动补齐）。

¥Or import globals explicitly (for better autocomplete in VS Code).

import 'zx/globals'

$command

使用 spawn 函数执行给定命令并返回 ProcessPromise。它支持同步和异步模式。

¥Executes a given command using the spawn func and returns ProcessPromise. It supports both sync and async modes.

const list = await $`ls -la`
const dir = $.sync`pwd`

所有通过 ${...} 的内容都会被自动转义并引用。

¥Everything passed through ${...} will be automatically escaped and quoted.

const name = 'foo & bar'
await $`mkdir ${name}`

无需添加额外的引号。请阅读 quotes 了解更多相关信息。

¥There is no need to add extra quotes. Read more about it in quotes.

如果需要，你可以传递参数数组：

¥You can pass an array of arguments if needed:

const flags = [
  '--oneline',
  '--decorate',
  '--color',
]
await $`git log ${flags}`

如果执行的程序返回非零退出代码，则会抛出 ProcessOutput。

¥If the executed program returns a non-zero exit code, ProcessOutput will be thrown.

try {
  await $`exit 1`
} catch (p) {
  console.log(`Exit code: ${p.exitCode}`)
  console.log(`Error: ${p.stderr}`)
}

ProcessOutput

class ProcessOutput {
  readonly stdout: string
  readonly stderr: string
  readonly signal: string
  readonly exitCode: number

  toString(): string // Combined stdout & stderr.
}

该过程的输出按原样捕获。通常，程序在末尾打印一个新行 \n。如果 ProcessOutput 用作其他某个 $ 进程的参数，zx 将使用 stdout 并修剪新行。

¥The output of the process is captured as-is. Usually, programs print a new line \n at the end. If ProcessOutput is used as an argument to some other $ process, zx will use stdout and trim the new line.

const date = await $`date`
await $`echo Current date is ${date}.`

许可

¥License

Apache-2.0

免责声明：这不是 Google 官方支持的产品。

¥Disclaimer: This is not an officially supported Google product.