# @discoveryjs/cli 中文文档

规范地址：https://npmcn.com/package/%40discoveryjs/cli/

版本：2\.15\.0
npm 元数据更新时间：2026-07-09T13:54:02.728Z
中文译文更新时间：2026-11-12T11:30:35.019Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：291 kB，63 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：12 个
- peer 依赖：@discoveryjs/discovery ^1\.0\.0-beta\.74
- 首次发布：2019-09-09T00:57:24.314Z
- 最新版本发布：2026-07-09T13:54:02.548Z
- 近 30 天下载量：8175（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 2 个）

## 中文简介

基于 Discovery.js 的 CLI 服务与构建项目的工具

## 安装

```sh
npm install @discoveryjs/cli
```

也可以使用：`pnpm add @discoveryjs/cli`、`yarn add @discoveryjs/cli`、`bun add @discoveryjs/cli`

## README

![Discovery.js project logo](https://user-images.githubusercontent.com/270491/48985803-1563ae80-f11d-11e8-92c0-e07fbf0bcd94.png)

# 用于发现.js 的工具

[![NPM version](https://img.shields.io/npm/v/@discoveryjs/cli.svg)](https://www.npmjs.com/package/@discoveryjs/cli) [![Twitter](https://badgen.net/badge/follow/@js_discovery?icon=twitter)](https://twitter.com/js_discovery)

CLI 工具,用于根据 [发现.js](https://github.com/discoveryjs/discovery)

-   [安装](https://npmcn.com/package/%40discoveryjs/cli/#readme-install)
-   [图标](https://npmcn.com/package/%40discoveryjs/cli/#readme-commands)
    -   [发现(服务器)](https://npmcn.com/package/%40discoveryjs/cli/#readme-discovery-serve)
    -   [发现-建设(建设)](https://npmcn.com/package/%40discoveryjs/cli/#readme-discovery-build-build)
-   [模式](https://npmcn.com/package/%40discoveryjs/cli/#readme-modes)
    -   [单一模式](https://npmcn.com/package/%40discoveryjs/cli/#readme-single-model)
    -   [多个模型](https://npmcn.com/package/%40discoveryjs/cli/#readme-multiple-models)
    -   [无型号](https://npmcn.com/package/%40discoveryjs/cli/#readme-model-free)
-   [配置](https://npmcn.com/package/%40discoveryjs/cli/#readme-configuration)
    -   [模型配置](https://npmcn.com/package/%40discoveryjs/cli/#readme-model-config)
    -   [多模式配置](https://npmcn.com/package/%40discoveryjs/cli/#readme-multi-model-config)
    -   [配置视图](https://npmcn.com/package/%40discoveryjs/cli/#readme-configure-view)
-   [许可证](https://npmcn.com/package/%40discoveryjs/cli/#readme-license)

## 安装

```
npm install @discoveryjs/cli
```

## 图标

### 发现(服务器)

```
Usage:

    discovery [config] [options]

Options:

        --bail                    Exit immediately on first warmup task failure
        --no-bg-update            Disable background data cache updates
        --no-cache                Disable data caching
        --cache-persistent        Use persistent caches system
        --cachedir [dir]          Path to store cache files (using .discoveryjs-cache by default when
                                  [dir] is not set)
        --no-check-cache-ttl      Disable data cache TTL checking before using it
    -c, --config <filename>       Path to config (JavaScript or JSON file), if not specified then looking
                                  for .discoveryrc.js, .discoveryrc.json, .discoveryrc or "discovery"
                                  section in package.json in the listed order
        --cors                    Enable CORS, i.e. allows data fetching for any origin
        --no-dev                  Disable using Discovery.js "src" assets when available (disables
                                  discovery-dev condition)
        --embed [mode]            Specify an embed API: by-config (default), enable (when [mode] omitted)
                                  or disable
        --experimental-jsonxl     Enable experimental binary data encoding (codename JSONXL)
    -h, --help                    Output usage information
        --no-minify               Disable JS and CSS minification
    -m, --model <name>            Specify a model (multi-model mode only)
        --no-model-data-upload    Disable model data upload feature
        --no-model-download       Disable model download feature
        --no-model-reset-cache    Disable model cache reset feature
    -p, --port <n>                Listening port (default: 8123)
        --prebuild [path]         Prebuild model's static in path (path is optional, `build` by default)
        --tmpdir <dir>            Path to directory of temporary cache files which are generating before
                                  committing to cache directory
    -v, --version                 Output version
        --no-warmup               Disable model's data cache warm up on server start
```

要创建和启动您脚本中的服务器, 请使用 `createServer()` 返回的方法 [`express`应用程序](https://expressjs.com/en/api.html#app)数字 :

```js
const discovery = require('@discoveryjs/cli');
const PORT = 1234;

discovery.createServer({ /* options */ }).listen(PORT, function() {
    console.log(`Server listen on http://localhost:${this.address().port}`);
});
```

### 发现-建设(建设)

```
Usage:

    discovery-build [config] [options]

Options:

        --asset-names [pattern]         Pattern for file names of the asset files corresponding to each model
        --no-cache                      Disable data caching
        --cachedir [dir]                Path to store cache files (using .discoveryjs-cache by default when [dir]
                                        is not set)
        --check-cache-ttl               Check data cache TTL before using it, option enforces to use actual
                                        (according to TTL) data only
        --clean                         Clean the output directory before emit a build files
    -c, --config <filename>             Path to config (JavaScript or JSON file), if not specified then looking
                                        for .discoveryrc.js, .discoveryrc.json, .discoveryrc or "discovery"
                                        section in package.json in the listed order
        --no-data                       Don't include data into a model build
        --no-data-compression           Disable HTML embedded data compression, when --single-file option is used
        --no-dev                        Disable using Discovery.js "src" assets when available (disables
                                        discovery-dev condition)
        --embed [mode]                  Specify an embed API: by-config (default), enable (when [mode] omitted)
                                        or disable
        --entry-names [pattern]         Pattern for file names of the output HTML files corresponding to each model
        --exclude-model-on-data-fail    Exclude models from the result if their data generation fails, ignoring
                                        the failure instead of halting the build (exit code: 1)
        --experimental-jsonxl           Enable experimental binary data encoding (codename JSONXL)
    -h, --help                          Output usage information
        --no-minify                     Disable JS and CSS minification
    -m, --model <name>                  Specify a model (multi-model mode only)
        --no-model-data-upload          Ignore model data upload feature setup in config
        --model-download                Enable model download feature
        --model-reset-cache             Enable model cache reset feature
    -o, --output <path>                 Path for a build result (`build` by default)
        --pretty-data [indent]          Pretty print of model data if any
        --script-external [pattern]     Mark a file or a package as external to exclude it from script bundle
                                        (see https://esbuild.github.io/api/#external). Use "all" value (without
                                        quotes, a shorthand for "./node_modules/*") to disable all the npm
                                        packages from the bundle
        --script-format [format]        Output format for the script files: esm (default), cjs or both
        --script-names [pattern]        Pattern for file names of the script files corresponding to each model
        --serve-only-assets             Include server only assets into build
    -s, --single-file                   Output a model build as a single HTML file per model
        --single-file-data [side]       Used to specify where to locate data: external (default), inline (default
                                        when --single-file is used), both
        --sourcemap [mode]              Enable source map generation, optional "mode" can be: linked (default,
                                        when [mode] is omitted), external or inline
                                        (see https://esbuild.github.io/api/#sourcemap for detail)
        --tmpdir <dir>                  Path to directory of temporary cache files which are generating before
                                        committing to cache directory
    -v, --version                       Output version
```

## 模式

发现CLI允许定义一个或多个预先定义的模型. 一个模型是数据获取脚本的构成,准备数据函数和一组页面,视图和其他帮助者. 模型的所有部分都是可选的. CLI 命令可能根据配置在以下模式下工作(参见 [配置](https://npmcn.com/package/%40discoveryjs/cli/#readme-configuration):

-   `single` – 单一模式,当不涉及索引页时. 当配置没有时启用 `models` 字段,或 `--model` 使用选项;
-   `multi` –多模型模式,一组列出模型的模型和索引页. 当配置包含时启用 `models` 字段和无 `--model` 使用选项;
-   `modlefree` – 模型自由模式, 当没有指定任何模型时. 未指定配置时启用

### 单一模式

此模式在您需要服务或只构建单一模式时使用. 要启用此模式, 您的配置不能包含 `models` 字段或命令应带有 `--model` 选项(即:. `discovery --model model-slug`) (中文(简体) ). 在这个模式下,根路由将导致模型的默认页面.

### 多个模型

如果一个单一服务应当服务多个模型,您可以使用多模型模式. 要激活此模式, 配置必须包含 `models` 字段,定义每个模型的配置。 在此模式发现中会显示模型选择页为索引页. 每个模型都会有自己的路由命名空间(即. `slug`),也可以在模型和索引页面之间切换.

### 无型号

在这个模式中,没有任何预定义的模型. 然而,您可以通过点击"Load Data"按钮来上传任何数据,或者将'n'drop文件右拖入浏览器并发现. 找不到配置文件时使用此模式 .

## 配置

配置文件有几种格式的支持(下面列出的优先级将只使用一种格式):

-   `.discoveryrc.js` (贾瓦脚本)
-   `.discoveryrc.json` (杰森语)
-   `.discoveryrc` (与 `.discoveryrc.json`(中文(简体) )
-   `discovery` 属性在 `package.json` (杰森语)

配置文件可以通过下列方式明确指定: `--config` 选项。 当配置找不到时, `modelfree` 模式正在使用.

### 模型配置

模型配置包含以下字段(所有字段均为可选) :

-   `name` - 模型名称(在标题中使用)
-   `version` - 该模型的版本,在指定时可以用于应用程序头
-   `description` - 模型的描述,在指定时可用于应用程序头
-   `icon` — 模型图标图像路径, 指定时可在应用程序头中使用
-   `meta` - 模型中的任何数据(应可序列到JSON) `setup.js`
-   `data` - 返回的函数 `any | Promise<any>` 或导出默认函数的模块路径(CommonJS或无害环境管理)。 该函数的结果是用于模型;必须可序列到JSON(即目前没有循环引用)
-   `encodings` – 一个模块的路径,它暴露出一系列编码配置,用于在加载到JavaScript值时转换有效载荷数据. 此选项只有在得到Discovery.js(在版本中添加)支持的情况下才会产生效果 `1.0.0-beta.83`) (中文(简体) ).
-   `prepare` - (折旧,使用) `setup` 取而代之的是,一个模块(CommonJS或ESM)的路径,默认导出一个在数据被装入后但在使用之前引用的函数(例如,在数据中添加循环引用和关系,标记数据对象,为查询引擎添加注释和/或帮助等)
-   `setup` - 模块的路径(CommonJS或无害环境管理),其功能在应用所有扩展后要求创建模型
-   `favicon` — favicon 图像路径; 未设置时继承父配置
-   `viewport` - 价值 `<meta name="viewport">`; 未设置时继承父配置
-   `darkmode` - 设置暗模特性;未设置时继承父配置
-   `upload` - 上传数据特性的设置;未设置时继承父配置
-   `embed` - 明确启用或禁用嵌入特性(默认) `false`(中文(简体) )
-   `download` - 下载特性的默认值;未设定时继承父配置
-   `view` - 设置模型的观点(见 [配置视图](https://npmcn.com/package/%40discoveryjs/cli/#readme-configure-view)(中文(简体) )
-   `routers` - 输出一个函数的模块的一系列路径(`function(router, modelConfig, options): void`),扩展模型路由器
-   `cache` - 允许缓存数据
-   `cacheTtl` - 指定数据缓存的活时间。 当数据缓存变得太老了,在下次请求时会生成新的数据. 值可能是数字(毫秒)或字符串(例如. `"1m"`, (中文(简体) ), `"1 hour 30 mins"` 等; 见 [解析长度](https://www.npmjs.com/package/parse-duration) 可能值的说明)
-   `cacheBgUpdate` – 指定从上次缓存一刻开始的时间段来更新. 一旦生成新的缓存,它将被用于即将到来的请求. 值可能是数字(毫秒)或字符串(例如. `"1m"`, (中文(简体) ), `"1 hour 30 mins"` 等; 见 [解析长度](https://www.npmjs.com/package/parse-duration) 可能值的说明)

示例

```js
const path = require('path');

module.exports = {
    name: 'My dashboard',
    data: './path/to/generate-data-script.js',
    encodings: path.join(__dirname, 'path/to/encodings.js'),
    prepare: path.join(__dirname, 'path/to/prepare.js'),
    favicon: './path/to/favicon.png',
    viewport: 'width=device-width, initial-scale=1',
    view: {
        basedir: __dirname,
        assets: [
            './ui/page/default.js',
            './ui/view/model-custom-view.css',
            './ui/view/model-custom-view.js',
            './ui/sidebar.css',
            './ui/sidebar.js'
        ]
    }
};
```

### 多模式配置

多个模型与一个单一的切入点,一个定义索引页面的设置,模型及其基础配置的配置相融合. 配置应当为 JSON 或导出对象提供以下属性(所有属性均为可选) :

-   `name` - 发现实例的名称(在标题中使用)
-   `version` – 索引页面的版本, 指定时可以在应用程序头中使用
-   `description` - 对索引页的描述,在指定时可以在应用程序头中使用
-   `icon` - 索引页图标图像路径
-   `models` - 具有模型配置的对象,每个条目用作弹簧的密钥和用作配置的值
-   `modelBaseConfig` – 与模型的配置相同,以模型配置作为基础,即. `{ ...modelBaseConfig, ...modelConfig }` 将使用
-   `encodings` – 一个模块的路径,它暴露出一系列编码配置,用于在加载到JavaScript值时转换有效载荷数据. 此选项只有在得到Discovery.js(在版本中添加)支持的情况下才会产生效果 `1.0.0-beta.83`) (中文(简体) ).
-   `routers` - 输出一个函数的模块的一系列路径(`function(router, modelConfig, options): void`扩展应用程序路由器
-   `favicon` - favicon图像路径
-   `viewport` - 价值 `<meta name="viewport">`
-   `darkmode` - 设置暗模特性( 默认) `"auto"`(中文(简体) )
-   `upload` - 上传数据特性的默认值( 默认值) `false`(中文(简体) )
-   `embed` - 明确启用或禁用嵌入特性(默认) `false`(中文(简体) )
-   `download` - 下载功能的默认值( 默认值) `true`(中文(简体) )
-   `view` - 设置索引页面浏览(见 [配置视图](https://npmcn.com/package/%40discoveryjs/cli/#readme-configure-view)(中文(简体) )

示例

```js
module.exports = {
    name: 'Dashboards hub',
    favicon: './path/to/favicon.png',
    models: {
        one: './path/to/model/config',
        two: require('./path/to/model/config'),
        three: { /* model config */ }
    }
};
```

### 配置视图

-   `basedir` - 解决相对路径的目录
-   `assets` - 各种路径 `.js`, (中文(简体) ), `.ts` 财务报告和审定财务报表 `.css` 文件

> js 文件有自己的范围(作为模块),并附有参考文献 `discovery` 这说明 `App` 实例 `@discoveryjs/discovery`

-   `serveOnlyAssets` - 与 `assets`,但这些资产只有在该模型服务于 `serve` 命令,或者当模型用 `--serve-only-assets` 选项(默认损坏)
-   `noscript` - 函数或路径,用于导出一个函数生成内容的模块 `<noscript>` 标记; 函数可以取两个参数: `getData` aync 函数返回数据,以及 `setup` 对象
-   `inspector` - 禁用查看检查器的选项( 默认) `true`(中文(简体) )
-   `router` - 禁用默认路由器的选项( 默认) `true`(中文(简体) )
-   `bundles` - 额外捆绑

```js
const path = require('path');

module.exports = {
    ...
    view: {
        basedir: __dirname,
        assets: [
            './ui/page/default.js',
            './ui/view/model-custom-view.css',
            './ui/view/model-custom-view.js',
            './ui/sidebar.css',
            './ui/sidebar.js'
        ],
        bundles: {
            'worker.js': './path/to/entry/point.js',
            'some-styles.css': './path/to/entry/point.css'
        }
    }
};
```

## 许可证

麻省理工学院

## 常见问题

### @discoveryjs/cli 是什么？

基于 Discovery\.js 的 CLI 服务与构建项目的工具

### 如何安装 @discoveryjs/cli？

在项目目录运行 npm install @discoveryjs/cli，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@discoveryjs/discovery（^1\.0\.0-beta\.74）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 discovery、discovery-build，可以用 npx discovery 直接运行。

### @discoveryjs/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/discoveryjs\_\_cli 是否存在。

### @discoveryjs/cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @discoveryjs/cli 需要什么版本的 Node\.js？

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

### @discoveryjs/cli 可以商用吗？

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

### @discoveryjs/cli 的下载量有多少？

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

### @discoveryjs/cli 还在维护吗？

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