# @foundryvtt/foundryvtt-cli 中文文档

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

版本：3\.0\.5
npm 元数据更新时间：2026-10-09T20:34:46.111Z
中文译文更新时间：2026-11-15T10:18:41.652Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：83.1 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>17\.0\.0
- 运行依赖：7 个
- 首次发布：2023-03-29T00:50:17.277Z
- 最新版本发布：2026-10-09T20:34:45.724Z
- 近 30 天下载量：31854（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 3 个）

## 中文简介

创建 VTT 的官方 CLI

## 安装

```sh
npm install @foundryvtt/foundryvtt-cli
```

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

## README

# 铸币局

官方创始人 VTT CLI

## 安装

```bash
npm install -g @foundryvtt/foundryvtt-cli
```

## 使用量

### 帮助

```bash
fvtt --help
```

### 当前 CLI 版本

```bash
fvtt --version
```

### 配置

```bash
fvtt configure
```

确定您的配置是否正确, 如果不正确, 则提示您修复 .

#### 视图

```bash
fvtt configure view
```

查看您的当前配置 .

#### 设定

```bash
fvtt configure set "key" "value"
```

设定配置值 .

#### 获取

```bash
fvtt configure get "key"
```

获得配置值 .

#### 路径

```bash
fvtt configure path
```

输出您的配置文件路径 .

### 发射

```bash
fvtt launch
```

(原始内容存档于2017-03-21). Launces Foundary VTT. 可用的选项有:

-   `--demo` - 以演示模式启动Foundry VTT.
-   `--port 30000` - 在一个特定端口上发射Foundry VTT.
-   `--world my-world` - 发射Foundry VTT 直接进入一个特定的世界.
-   `--noupnp` - 禁用 UPnP 端口转发.
-   `--noupdate` - 禁用自动更新检查.
-   `--adminKey "ABC123"` - 保护Foundry VTT的设置屏幕的管理员密钥.

### 软件包

```bash
fvtt package
```

输出当前工作包( 如果有的话) .

#### 工人

```bash
fvtt package workon "1001-fish" --type "Module"
```

切换到一个特定的软件包, 从而无需通过 `--type` 财务报告和审定财务报表 `--id` 到其他软件包命令.

#### 清除

```bash
fvtt package clear
```

清除当前工作包.

#### 卸货

```bash
fvtt package unpack "compendiumName"
```

从当前软件包/packs/目录中读取一个数据库,并将每个文档作为序列化对象写入自己的文件. 有很多选项可以自定义输出, 检查 `fvtt package unpack --help` 更多信息.

如果您在终端运行此命令, 它应该输出哪些新文件被写入或更新 。 例如:

```bash
Unpacking "foundrydatav11/Data/modules/mymodule/packs/myitems" to "git/mymodule/jsons/myitems"
Wrote My_Item_Name_hPLXDSGyHzlupBS2.json
```

#### 包装

```bash
fvtt package pack "compendiumName"
```

读取序列化对象的目录并将其写入当前套件/包/目录的数据库. 有许多选项可以自定义操作, 检查 `fvtt package pack --help` 更多信息.

如果您在终端运行此命令, 它应该输出哪些新文件被写入或更新 。 例如:

```bash
Packing "git/mymodule/jsons/myitems" into "git/mymodule/packs/myitems"
Packed hPLXDSGyHzlupBS2 (My Item Name)
```

#### 子目录和模块

您可以为您的包目录创建子目录 。 例如,在一个模块中,模块.json可以为两个不同的系统定义一个项目包:

```json
"packs":[
    {
      "name": "mymodule_items_sfrpg",
      "label": "MyModule Items",
      "path": "packs/items/sfrpg",
      "type": "Item",
      "private": false,
      "system": "sfrpg"
    },
    {
      "name": "mymodule_items_pf2e",
      "label": "MyModule Items",
      "path": "packs/items/pf2e",
      "type": "Item",
      "private": false,
      "system": "pf2e"
    }
]
```

在 Foundry 数据文件夹中,这将创建以下文件夹等级: `Data/modules/mymodule/packs/items/sfrpg/` 财务报告和审定财务报表 `Data/modules/mymodule/packs/items/pf2e/`。 。 。 .

要打包和打包,请使用您为简编名称定义的路径 。 例如,要将jsons提取到您家目录中的文件夹:

```bash
fvtt package unpack -n "items/pf2e" --outputDirectory "~/jsons/items/pf2e"
fvtt package unpack -n "items/sfrpg" --outputDirectory "~/jsons/items/sfrpg"
```

要使用子目录来包装它们 :

```bash
fvtt package pack -n "items/pf2e" --inputDirectory "~/jsons/items/pf2e" --outputDirectory "packs"
fvtt package pack -n "items/sfrpg" --inputDirectory "~/jsons/items/sfrpg" --outputDirectory "packs"
```

## 示例工作流程

```bash
fvtt configure
fvtt package workon "1001-fish"
fvtt package unpack "fish"
. . . // Make some updates to the files
fvtt package pack "fish"
```

## 发展

```bash
git clone
cd foundryvtt-cli
npm install
npm run build
npm link
```

## API 密码

某些CLI的内部功能被暴露为可以被导入到其他项目的API.

### 示例使用

```js
import { compilePack, extractPack } from "@foundryvtt/foundryvtt-cli";

// Extract a NeDB compendium pack.
await extractpack("mymodule/packs/actors.db", "mymodule/packs/src/actors", { nedb: true });

// Compile a LevelDB compendium pack.
await compilePack("mymodule/packs/src/actors", "mymodule/packs/actors");
```

### `compilePack(src: string, dest: string, options?: object): Promise<void>`

将源文件汇编成简编包.

#### 参数

-   **弧 :** _字符串_ 包含源文件的目录 .
-   **暗点 :** _字符串_ 目标简编包.
-   **选项:** _对象_
    -   **内德布:** _布尔=虚假_ 是否在 NEDB 数据库中运行, 否则假设是一个 LevelDB 数据库 .
    -   **雅姆尔:** _布尔=虚假_ 源文件是否采用YAML格式,否则JSON会被假设.
    -   **日志 :** _布尔=虚假_ 是否将操作进度记录到控制台 .
    -   **递归 :** _布尔=虚假_ 是否在下面重现为子目录 **曲线**,否则,只有源文件直接位于 **曲线** 将被使用.
    -   **转换 Entry :** _(条目:对象:承诺<虚假>_ 在每个条目上调用的函数 。 正在返回 _虚假_ 表示该条目应予删除.

### `extractPack(src: string, dest: string, options?: object): Promise<void>`

将简编内容抽取到每个主文档的单个源文件中.

#### 参数

-   **弧 :** _字符串_ 源头简编包.
-   **暗点 :** _字符串_ 将提取出的文件写入目录 .
-   **选项:** _对象_
    -   **内德布:** _布尔=虚假_ 是否在 NEDB 数据库中运行, 否则假设是一个 LevelDB 数据库 .
    -   **雅姆尔:** _布尔=虚假_ 源文件是否采用YAML格式,否则JSON会被假设.
    -   **扬子选项 :** _对象=_ 要传递给的选项 `yaml.dump` 将文档序列化.
    -   **日志 :** _布尔=虚假_ 是否将操作进度记录到控制台 .
    -   **文件夹 :** _布尔=虚假_ 创建一个目录结构,与包的文件夹文档相匹配。 文件夹文档被写入与名称匹配的目录 `_Folder.{yml|json}`。 。 。 .
    -   **文档类型 :** _字符串_ 对于NeDB操作, a **文档类型** 必须提供。 这应该和这包一样 _类型_ 区域 _模块.json_ 或者说 _系统.json_。 。 。 .
    -   **转换 Entry :** _(条目:对象,上下文:对象:承诺<false|void>)_ 在每个条目上调用的函数 。 正在返回 _虚假_ 表示该条目应予删除.
    -   **变换Name :** _(条目:对象,上下文:对象:承诺<string|void>)_ 在每个条目上调用的函数 。 从此返回的值将作为条目的文件名, 并且必须包含适当的文件扩展名 。 如果不返回任何信息, 将使用自动生成的名称 .
    -   **变换文件夹Name :** _(条目:对象:承诺<字符串>_ 用于生成已提取文件夹文档的目录名的函数 `folders` 选项.
    -   **已串行化 :** _(内容:字符串,上下文:对象):承诺_ 对被序列化的内容调用的一个函数 。 从此返回的值将写入磁盘 .
    -   **扩展冒险 :** _布尔_ 将嵌入"冒险"中的文档写入自己的文档. 如果 `folders` 还提供了选项,将“冒险”作为文件夹处理,并写入 `_Adventure.{yml|json}` 改为 `_Folder.{yml|json}`此外,它的所有条目都按文件类型分组为子文件夹.
    -   **省略挥发 :** _布尔_ 解开时, 将候选条目相对于一个已有条目, 并且只有在非挥发性字段改变时才写 。 目前, `_stats.createdTime`, (中文(简体) ), `_stats.modifiedTime`, (中文(简体) ), `_stats.lastModifiedBy`, (中文(简体) ), `_stats.systemVersion`,以及 `_stats.coreVersion` 被认为是不稳定的.
    -   **json 选项 :** _对象_
        -   **替换器 :** _(键:字符串, 值: 任意): 任意一个 QQ 箭头 < string > 数字 >_ 对象中要包含的替换器函数或一系列属性名称在生成的字符串中.
        -   **空间 :** _字符串qq数字_ 多个空格或用于缩进的字符串 .

## 捐款

欢迎拉动请求。 对于重大变动,请先开出一个问题来讨论你想要改变什么.

## 常见问题

### @foundryvtt/foundryvtt-cli 是什么？

创建 VTT 的官方 CLI

### 如何安装 @foundryvtt/foundryvtt-cli？

在项目目录运行 npm install @foundryvtt/foundryvtt-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 fvtt，可以用 npx fvtt 直接运行。

### @foundryvtt/foundryvtt-cli 支持 TypeScript 吗？

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

### @foundryvtt/foundryvtt-cli 支持 ESM 还是 CommonJS？

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

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

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

### @foundryvtt/foundryvtt-cli 可以商用吗？

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

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

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

### @foundryvtt/foundryvtt-cli 还在维护吗？

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