# @cybozu/duck 中文文档

规范地址：https://npmcn.com/package/%40cybozu/duck/

版本：0\.36\.1
npm 元数据更新时间：2026-09-28T09:17:04.821Z
中文译文更新时间：2026-11-14T13:48:30.420Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cybozu/duck
原文对照：https://npmcn.com/package/%40cybozu/duck/?lang=original
项目主页：https://github.com/cybozu/duck
源码仓库：https://github.com/cybozu/duck

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：115 kB，65 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：20 个
- peer 依赖：google-closure-compiler \>=20180910\.1\.0
- 首次发布：2020-02-07T06:50:42.355Z
- 最新版本发布：2026-09-28T09:17:04.604Z
- 近 30 天下载量：2019（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 1 个）

## 中文简介

与Google关闭编译器/Library/Templates一起服务并构建了应用程序. 一种替代活泼的人.

## 安装

```sh
npm install @cybozu/duck
```

也可以使用：`pnpm add @cybozu/duck`、`yarn add @cybozu/duck`、`bun add @cybozu/duck`

## README

# @cybozu/duck (英语)

与Google关闭编译器/Library/Templates一起服务并构建了应用程序. 替代 [爱人](https://github.com/bolinfest/plovr)。 。 。 .

[![npm version](https://badge.fury.io/js/%40cybozu%2Fduck.svg)](https://badge.fury.io/js/%40cybozu%2Fduck) [![](https://github.com/cybozu/duck/workflows/Test/badge.svg)](https://github.com/cybozu/duck/actions?workflow=Test) [![](https://github.com/cybozu/duck/workflows/Lint/badge.svg)](https://github.com/cybozu/duck/actions?workflow=Lint)

## 安装

```console
$ npm i -D @cybozu/duck
```

## 使用量

```
duck <command>

Commands:
  duck serve [entryConfigDir]     Start dev server
  duck build [entryConfigDir]     Build Soy, deps.js and JS
  duck build:js [entryConfigDir]  Compile JS files
  duck build:soy                  Compile Soy templates
  duck build:deps                 Generate deps.js
  duck clean:soy                  Remove all compiled .soy.js
  duck clean:deps                 Remove generated deps.js
  duck completion                 Generate completion script for bash/zsh

Options:
  -v, --version  Show version number                                                     [boolean]
  -h, --help     Show help                                                               [boolean]

CLI options overwrite config file
```

### `duck serve`

```
duck serve [entryConfigDir]

Start dev server

Options:
  --inputsRoot            A root directory to serve                                       [string]
  --closureLibraryDir     A root directory of Closure Library                             [string]
  --depsJs                A path to deps.js to save and load                              [string]
  --depsWorkers           The number of workers to analyze deps              [number] [default: 4]
  --config                A path to duck.config.js, the extension can be ommited          [string]
  --nonTTY, --noTTY, -n   Output in nonTTY mode                         [boolean] [default: false]
  --skipInitialBuild, -s  Skip initial building of Soy and deps.js      [boolean] [default: false]
  --port                  A port number to listen                         [number] [default: 9810]
  --host                  A host to listen                         [string] [default: "localhost"]
  -v, --version           Show version number                                            [boolean]
  -h, --help              Show help                                                      [boolean]
```

### `duck build`

```
duck build [entryConfigDir]

Build Soy, deps.js and JS

Options:
  --entryConfigs, -e      Entry config files (this option ignores entryConfigDir)          [array]
  --closureLibraryDir     A root directory of Closure Library                             [string]
  --config                A path to duck.config.js, the extension can be ommited          [string]
  --concurrency, -c       Concurrency limit of Closure Compiler                           [number]
  --batch                 Build in batch mode (on AWS or local for debug)[choices: "aws", "local"]
  --reporters             Test reporters ("text", "xunit" or "json")   [array] [default: ["text"]]
  --reporterOptions       Test reporter options
  --printConfig, -p       Print effective configs for compilers         [boolean] [default: false]
  --depsJs                A path to deps.js to save and load                              [string]
  --nonTTY, --noTTY, -n   Output in nonTTY mode                         [boolean] [default: false]
  --depsWorkers           The number of workers to analyze deps              [number] [default: 4]
  --skipInitialBuild, -s  Skip initial building of Soy and deps.js      [boolean] [default: false]
  --soyJarPath            A path to Soy.jar                                               [string]
  --soyFileRoots          Root directories of soy files                                    [array]
  --soyClasspaths         Classpaths for Closure Templates                                 [array]
  --watch, -w             Re-compile incrementally when files change    [boolean] [default: false]
  -v, --version           Show version number                                            [boolean]
  -h, --help              Show help                                                      [boolean]
```

## `duck.config.js`

创建配置文件 `duck.config.js` 或者说 `duck.config.json` 在您的项目根上. 从位置设定每个路径为相对路径 `duck.config.js`。 。 。 .

```js
module.exports = {
  /**
   * Common settings
   */
  // (Required) A path to Closure Library direcotry
  closureLibraryDir: "node_modules/google-closure-library",
  // (Required) A directory where entry config JSONs are stored flat
  entryConfigDir: "entry-configs",

  /**
   * Generating and loading deps.js
   */
  // A path to deps.js to save and load in build and serve commands
  depsJs: "build/deps.js",
  // Directories ignored when building deps.js
  depsJsIgnoreDirs: ["src/third_party"],
  // The number of workers to build deps.js. Node v10 uses processes and node v12+ uses threads. (default: 4)
  depsWorkers: 2,

  /**
   * Building Soy
   */
  // (Required) A path to Closure Templates JAR
  soyJarPath: "lib/closure-templates.jar",
  // (Required) Directories where Closure Templates .soy files are stored
  soyFileRoots: ["src/js"],
  // Classpaths for Closure Templates plugins
  soyClasspaths: ["lib/plugin.jar"],
  // Send srcs to closure-templates as relative paths from this.
  // Also change cwd to this and run closure-templates. (default: undefined)
  soySrcsRelativeFrom: "src",
  // Options for Closure Templates CLI
  soyOptions: {
    outputDirectory: "src/js/soy",
  },

  /**
   * Compiling JavaScript
   */
  // Concurrency of Closure Compiler (default: 1,000 if AWS batch mode, otherwise 1)
  concurrency: 4,
  // Build in batch mode with faast.js on "aws" for production or "local" for debug (default: undefined)
  batch: "aws",
  // Custom Closure Compiler package used in AWS batch mode (default: undefined)
  batchAwsCustomCompiler: {
    name: "my-custom-closure-compiler",
    version: "^1.0.0",
  },
  // Max chunk size in bytes for spliting return value from faastjs module (default: 204,800 (200kb))
  batchMaxChunkSize?: number;
  // Options for faast.js in batch mode. See https://faastjs.org/docs/api/faastjs.awsoptions
  batchOptions: {},
  // Reporters (choose from "json", "text" or "xunit")
  reporters: ["text", "xunit"],
  // Options for each test reporter
  reporterOptions: {
    text: {
      // Output errors to stderr or not
      stderr: false,
      // A directory where reporters output
      outputDir: "test-results/text",
    },
    xunit: {},
  },

  /**
   * Serve
   */
  // (Required) A root directory scanned to build deps.js and delivered as static assets
  inputsRoot: "src/inputs",
  // Hostname for serve command (default: 0.0.0.0)
  host: "localhost",
  // Port number for serve command (default: 9810)
  port: 1234,
  // Use HTTP/2 in serve command (deafult: false)
  http2: true,
  // Settings for HTTPS (HTTP/2) (default: not specified, HTTP is used)
  https: {
    // A path to a private key
    keyPath: "path/to/key.pem",
    // A path to a self-signed certificate
    certPath: "path/to/cert.pem",
  },
};
```

又见 [`examples`](https://npmcn.com/package/%40cybozu/duck/examples)。 。 。 .

## 限制

-   关闭编译器 `v20180910.0.0`
-   关闭模板 QQ `2019-03-07`
-   关闭图书馆 < `v20200224.0.0` (部分内容)
    -   注:闭合编译器不支持 `goog.requireType()` 在块特性中. 关闭 图书馆 `v20200224`\+ 包含 `goog.requireType()`,所以你不能用块. 见 [块与 goog. requireType 相不相通 ! 发行 #3931 • 谷歌/闭合-编译器](https://github.com/google/closure-compiler/issues/3931)
-   google - 关闭 - 窗口 `v20210406`

## 提示

### 使用 AWS Lambda 批量模式

鸭子提供批量模式,在AWS Lambda上同时编译所有入口 [恶心的js](https://faastjs.org/)。 。 。 .

1.  在节点设置 AWS 证书(参见 [AWS 文档](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html)(中文(简体) )
2.  配置 `batchOptions` 内 `duck.config.js`用于 faast.js 作为 [AWS 选项](https://faastjs.org/docs/api/faastjs.awsoptions)。 。 。 .

```js
const closureVersion = require("google-closure-compiler/package.json").version;

module.exports = {
  batchOptions: {
    region: "ap-northeast-1",
    awsLambdaOptions: {
      Runtime: "nodejs10.x",
    },
    include: ["path/to/your/source/**/*.js"],
    exclude: ["**/*_spec.js"],
    packageJson: {
      dependencies: {
        "google-closure-compiler-linux": closureVersion,
        "google-closure-library": closureVersion,
      },
    },
  },
};
```

3.  运行 `build` 或者说 `build:js` 命令为 `--batch aws`。 。 。 .

```console
$ duck build --batch aws
```

#### 在批量模式下如何调试 ?

-   使用 `--batch local` 页:1 [本地调试](https://faastjs.org/docs/local)
-   使用 `DEBUG=faast:info` 或者说 [其他日志级别](https://faastjs.org/docs/workflow#debug-environment-variable) 获取更多的调试信息
-   获取 `logUrl` 从调试信息中查看并在 Cloud Watch 日志中查看
-   使用 `FAAST_PACKAGE_DIR=foo/bar` 调查寄给Lambda的包裹

又见 [fast.js 文档](https://faastjs.org/docs/api/faastjs.awsoptions) 更多信息.

### 如何在 HTTPS 和 HTTP2 中使用 `duck serve`? 吗?

[创建自签名证书](https://stackoverflow.com/a/10176685) 喜欢

```console
$ openssl req -x509 -newkey rsa:4096 -keyout duck-key.pem -out duck-cert.pem -days 365 -nodes -subj '/CN=localhost'
```

然后指定并启用 `http2` 内 `duck.config.js`。 。 。 .

```js
module.exports = {
  http2: true,
  https: {
    keyPath: "./path/to/duck-key.pem",
    certPath: "./path/to/duck-cert.pem",
  },
};
```

### bash/zsh- 命令和选项的补全

初始设定 :

```console
$ duck completion >> ~/.bashrc
# or
$ duck completion >> ~/.zshrc
```

然后,您可以通过 塔布 来啊!

```console
$ duck build:<TAB>
build:deps  -- Generate deps.js
build:js    -- Compile JS files
build:soy   -- Compile Soy templates
```

## 发展

此寄存器是一个 [小时](https://pnpm.io/) 工作空间。 根包子是: `@cybozu/duck` 本身和 `examples/*` 私有工作空间软件包 依赖它通过 `workspace:*`。 。 。 .

```console
$ pnpm install
$ pnpm test                                 # clean, lint, build and unit tests
$ pnpm --recursive --filter "./examples/*" test
```

pnpm 只解决已发布至少7天的版本 (单位:千美元)`minimumReleaseAge` 内 `pnpm-workspace.yaml`) (中文(简体) ).

### 释放

释放是自动的 [请放行](https://github.com/googleapis/release-please)土地承诺 `master` 如下 [常规武器委员会](https://www.conventionalcommits.org/)请放行 保持发布 PR 与下一个版本和 ChangeGELOG 的更新. 合并 pR 创建 GitHub 发布并发布软件包到 npm 来源.

## 许可证

麻省理工学院许可证:Cybozu, Inc.

## 常见问题

### @cybozu/duck 是什么？

与Google关闭编译器/Library/Templates一起服务并构建了应用程序\. 一种替代活泼的人\.

### 如何安装 @cybozu/duck？

在项目目录运行 npm install @cybozu/duck，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：google-closure-compiler（\>=20180910\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 duck，可以用 npx duck 直接运行。

### @cybozu/duck 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cybozu/duck 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cybozu/duck 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cybozu/duck 可以商用吗？

@cybozu/duck 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cybozu/duck 的下载量有多少？

根据 npm 官方下载统计，@cybozu/duck 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,019 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cybozu/duck 还在维护吗？

最新版本 0\.36\.1 发布于 2026/09/28（1 个月前）；至今共发布 24 个版本，其中过去 12 个月发布了 1 个；首次发布于 2020/02/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。