谷歌开源项目zx，在node中bash

🐚 zx

#!/usr/bin/env zx

await $`cat package.json | grep name`

let 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`,
])

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

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

1. 安装

npm i -g zx
Requirement: Node version >= 16.0.0

用于在远程主机上运行命令, 请看webpod.

2. 文档

在扩展名为.mjs的文件中编写脚本，以便在顶层使用await。如果你更喜欢.js扩展名，可以将脚本包装在void async function(){…}()中。

在zx脚本的开头添加以下shebang:

#!/usr/bin/env zx

现在你可以像这样运行你的脚本:

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

或者通过zx可执行文件:

zx ./script.mjs

所有函数($，cd, fetch等)都可以直接使用，无需任何导入。

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

import 'zx/globals'

$command

使用spawn func执行给定命令并返回ProcessPromise。

所有东西都经过${…}将自动转义并引用。

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

没有必要添加额外的引号。阅读更多关于它的引用。

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

如果需要，你可以传递一个参数数组:

You can pass an array of arguments if needed:

let 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}`)
}
ProcessPromise
class ProcessPromise extends Promise<ProcessOutput> {
  stdin: Writable
  stdout: Readable
  stderr: Readable
  exitCode: Promise<number>

  pipe(dest): ProcessPromise

  kill(): Promise<void>

  nothrow(): this

  quiet(): this
}

ProcessOutput

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

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

流程的输出按原样捕获。通常，程序在最后打印一个新行\n。如果ProcessOutput被用作其他$process的参数，zx将使用stdout并修剪新行。

let date = await $`date`
await $`echo Current date is ${date}.`
Functions
cd()

更改当前工作目录。

cd('/tmp')
await $`pwd` // => /tmp
fetch()

A wrapper around the node-fetch package.

let resp = await fetch('https://medv.io')
question()

readline包的包装器。

A wrapper around the readline package.

let bear = await question('What kind of bear is best? ')
sleep()
A wrapper around the setTimeout function.

await sleep(1000)
echo()

A console.log() alternative which can take ProcessOutput.

let branch = await $`git branch --show-current`

echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)
stdin()
Returns the stdin as a string.

let content = JSON.parse(await stdin())
within()

Creates a new async context.

await $`pwd` // => /home/path

within(async () => {
  cd('/tmp')

  setTimeout(async () => {
    await $`pwd` // => /tmp
  }, 1000)
})

await $`pwd` // => /home/path
let version = await within(async () => {
  $.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
  await $`nvm use 16`
  return $`node -v`
})
retry()

重试回调几次。将在第一次尝试成功后返回，或在指定尝试计数后抛出。

Retries a callback for a few times. Will return after the first successful attempt, or will throw after specifies attempts count.

let p = await retry(10, () => $`curl https://medv.io`)

// With a specified delay between attempts.
let p = await retry(20, '1s', () => $`curl https://medv.io`)

// With an exponential backoff.
let p = await retry(30, expBackoff(), () => $`curl https://medv.io`)
spinner()

Starts a simple CLI spinner.

await spinner(() => $`long-running command`)

// With a message.
await spinner('working...', () => $`sleep 99`)

Packages

以下包无需导入内部脚本即可使用。

• chalk package
  The chalk package.

console.log(chalk.blue('Hello world!'))

• fs package
  The fs-extra package.

let {version} = await fs.readJson('./package.json')

• os package
  The os package.

await $`cd ${os.homedir()} && mkdir example`

• path package
  The path package.

await $`mkdir ${path.join(basedir, 'output')}`

• globby package
  The globby package.

let packages = await glob(['package.json', 'packages/*/package.json'])

• yaml package
  The yaml package.

console.log(YAML.parse('foo: bar').foo)

• minimist package
  The minimist package available as global const argv.

if (argv.someFlag) {
  echo('yes')
}

• which package
  The which package.

let node = await which('node')

Configuration

$.shell

指定使用的shell。默认是哪个bash。

Specifies what shell is used. Default is which bash.

$.shell = ‘/usr/bin/bash’

Or use a CLI argument: --shell=/bin/bash

$.spawn

Specifies a spawn api. Defaults to require(‘child_process’).spawn.

$.prefix

Specifies the command that will be prefixed to all commands run.

Default is set -euo pipefail;.

Or use a CLI argument: --prefix=‘set -e;’

$.quote

Specifies a function for escaping special characters during command substitution.

$.verbose

Specifies verbosity. Default is true.

In verbose mode, zx prints all executed commands alongside with their outputs.

Or use the CLI argument --quiet to set $.verbose = false.

$.env

Specifies an environment variables map.

Defaults to process.env.

$.cwd

Specifies a current working directory of all processes created with the $.

The cd() func changes only process.cwd() and if no $.cwd specified, all $ processes use process.cwd() by default (same as spawn behavior).

$.log

Specifies a logging function.

import { LogEntry, log } from 'zx/core'

import { LogEntry, log } from 'zx/core'

$.log = (entry: LogEntry) => {
  switch (entry.kind) {
    case 'cmd':
      // for example, apply custom data masker for cmd printing
      process.stderr.write(masker(entry.cmd))
      break
    default:
      log(entry)
  }
}

Polyfills

__filename & __dirname

In ESM modules, Node.js does not provide __filename and __dirname globals. As such globals are really handy in scripts, zx provides these for use in .mjs files (when using the zx executable).

require()

In ESM modules, the require() function is not defined. The zx provides require() function, so it can be used with imports in .mjs files (when using zx executable).

let {version} = require('./package.json')

FAQ

Passing env variables

process.env.FOO = 'bar'
await $`echo $FOO`

Passing array of values

When passing an array of values as an argument to $, items of the array will be escaped individually and concatenated via space.

Example:

let files = [...]
await $`tar cz ${files}`

Importing into other scripts

It is possible to make use of $ and other functions via explicit imports:

#!/usr/bin/env node
import { $ } from 'zx'

await $date

Scripts without extensions

If script does not have a file extension (like .git/hooks/pre-commit), zx assumes that it is an ESM module.

Markdown scripts

The zx can execute scripts written as markdown:

zx docs/markdown.md

TypeScript scripts

import { $ } from ‘zx’

// Or

import ‘zx/globals’

void async function () {

await $ls -la

}()

Set “type”: “module” in package.json and “module”: “ESNext” in tsconfig.json.

Executing remote scripts

If the argument to the zx executable starts with https://, the file will be downloaded and executed.

zx https://medv.io/game-of-life.js

Executing scripts from stdin

The zx supports executing scripts from stdin.

zx << ‘EOF’

await $pwd

EOF

Executing scripts via --eval

Evaluate the following argument as a script.

cat package.json | zx --eval ‘let v = JSON.parse(await stdin()).version; echo(v)’

Installing dependencies via --install

// script.mjs:

import sh from ‘tinysh’

sh.say(‘Hello, world!’)

Add --install flag to the zx command to install missing dependencies automatically.

zx --install script.mjs

You can also specify needed version by adding comment with @ after the import.

import sh from ‘tinysh’ // @^1

Executing commands on remote hosts

The zx uses webpod to execute commands on remote hosts.

import { ssh } from ‘zx’

await ssh(‘user@host’)echo Hello, world!

Attaching a profile

By default child_process does not include aliases and bash functions. But you are still able to do it by hand. Just attach necessary directives to the $.prefix.

. p r e f i x + = ′ e x p o r t N V M D I R = .prefix += 'export NVM_DIR=.prefix+=

′

exportNVM

D

IR=HOME/.nvm; source $NVM_DIR/nvm.sh; ’

await $nvm -v

Using GitHub Actions

The default GitHub Action runner comes with npx installed.

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

  - name: Build
    env:
      FORCE_COLOR: 3
    run: |
      npx zx <<'EOF'
      await $`...`
      EOF

Canary / Beta / RC builds

Impatient early adopters can try the experimental zx versions. But keep in mind: these builds are ⚠️️__beta__ in every sense.

npm i zx@dev

npx zx@dev --install --quiet <<< ‘import _ from “lodash” /* 4.17.15 */; console.log(_.VERSION)’

License