命令行构建

不打开界面，用命令行产出发行构建或检查项目，供构建机与发版流程使用

Studio 可以从命令行构建项目，结束时返回状态码。这种方式不打开任何窗口，构建日志写到标准输出，产出的文件与构建发行包窗口产出的一致。

一次调用产出一份构建：一个变体、一个平台、一种格式。要产出第二个目标，再调用一次。

narraleaf-studio --build /projects/my-game

这条命令就是 Studio 自己的可执行文件：

Windows：安装目录下的 NarraLeaf Studio.exe
macOS：NarraLeaf Studio.app/Contents/MacOS/NarraLeaf Studio
Linux：解包目录下的 narraleaf-studio

下面的示例一律写作 narraleaf-studio。

选项

选项	取值	默认
`--build`	项目目录	必填
`--build-variant`	构建变体 id	`main`
`--build-target`	`windows`、`macos`、`linux`、`web`、`android`、`ios`	当前系统
`--build-format`	该平台的一种格式	桌面与 Web 为 `zip`，Android 为 `apk`，iOS 为 `ipa`
`--build-arch`	`x64`、`arm64`、`universal`	构建本机平台时取本机架构；在其他系统上构建 macOS 时取 `universal`，其余取 `x64`
`--build-output`	输出目录	项目内的 `dist`
`--build-report`	写出报告的文件	不写报告
`--build-allow-unsigned`	无取值	产物无法签名时中止构建
`--build-user-data-dir`	本次运行使用的配置目录	已安装的配置
`--build-signing`	本次运行使用的凭据文件	配置中已导入的凭据
`--build-setting`	`key=value`，可重复	配置中的设置

--选项值 与 --选项=值 两种写法都接受。--build-arch 只对桌面目标有效。给了构建选项却没给 --build 会被拒绝。

桌面与 Web 的格式为 zip、dir，以及该平台的安装包（Windows 为 nsis，macOS 为 dmg，Linux 为 appimage）。Android 产出 apk 或 aab，iOS 产出 ipa。每种系统能产出哪些桌面格式，见对构建机的要求。

状态码	含义
`0`	构建已写出产物
`1`	检查通过，构建未能完成
`2`	命令行无法执行，什么都没有打开
`3`	检查拒绝了这个项目
`4`	Studio 无法打开项目或工作区

构建报告

--build-report 对每一种结果都写出一个 JSON 文件，包括什么都没打开的那几种：

narraleaf-studio --build /projects/my-game --build-report /artifacts/report.json

文件里记录着结果与状态码、解析后的项目与构建请求、全部构建前检查结果、产物及其体积、这次构建是否带代码签名以及凭据来自哪里，还有带时间戳的完整构建日志。

构建前检查

命令行构建执行的检查与窗口里的一致。阻塞项会以状态码 3 中止构建，全部检查结果都会进入报告和日志。

开启构建前检查时，构建还会运行项目检查，并按级别一节所述中止构建。

目标平台可以携带代码签名却没有配置凭据时，构建中止。要接受未签名的产物，加上 --build-allow-unsigned。

为构建准备独立配置

一份配置同一时间只运行一个 Studio。Studio 正开着同一份配置时启动构建，会以状态码 4 中止。

--build-user-data-dir 让这次运行使用自己的配置目录：

narraleaf-studio --build /projects/my-game --build-user-data-dir /var/lib/narraleaf-agent/profile

新配置里没有任何签名凭据，也没有在 Studio 里配好的设置。构建需要的凭据用 --build-signing 给出，设置用 --build-setting 给出。

签名凭据

从构建窗口的签名一节导入的凭据，该配置下的每一次命令行构建都会使用，无需任何选项。

--build-signing 改为只为这一次运行提供凭据。它对文件中列出的平台生效，覆盖项目自身的选择，并且不会被导入到配置中。

narraleaf-studio --build /projects/my-game --build-signing /run/secrets/signing.json

{
  "windows": { "kind": "windows-pfx", "file": "certs/app.pfx", "passwordEnv": "PFX_PASSWORD" },
  "macos": {
    "kind": "macos-apple",
    "p12File": "certs/developer-id.p12",
    "p12PasswordEnv": "P12_PASSWORD",
    "notaryKeyFile": "certs/notary.p8",
    "notaryKeyId": "ABCD1234",
    "notaryIssuerId": "6a0e1111-2222-3333-4444-555566667777"
  }
}

每一项按平台命名：windows、macos、linux、android、ios。文件路径相对于凭据文件所在目录解析。

`kind`	字段
`windows-pfx`	`file`、`password`
`windows-store`	`subjectName` 或 `sha1`
`windows-azure`	`endpoint`、`codeSigningAccountName`、`certificateProfileName`、`publisherName`
`macos-keychain`	`identity`
`macos-apple`	`p12File`、`p12Password`
`android-keystore`	`file`、`alias`、`storePassword`、`keyPassword`
`ios-apple`	`p12File`、`provisioningProfileFile`、`p12Password`
`linux-gpg`	`keyId`；gpg 不在 PATH 上时另加 `gpgPath`

两种 macOS 凭据在带上 notaryKeyFile、notaryKeyId、notaryIssuerId 时会做公证，这三项必须同时给出。

每个密码字段都可以换成 <字段>Env，值是存放该密码的环境变量名：passwordEnv、p12PasswordEnv、storePasswordEnv、keyPasswordEnv。同一个字段两种写法都给会被拒绝。

存有密码的凭据文件，其敏感程度等同于旁边的密钥文件。Studio 只读取它，不会把其中任何内容写进日志或报告。

构建设置

--build-setting 为这一次运行提供设置：

narraleaf-studio --build /projects/my-game \
  --build-setting build.electronMirror=https://mirror.example/electron/

该选项可重复，只接受 build. 开头的设置。取值为空表示使用官方源。日志只列出这次运行收到了哪些设置，取值既不打印也不写进报告

三个下载镜像就是设置 → 网络中的设置：build.electronMirror 是 Electron 下载镜像，build.electronBuilderBinariesMirror 是构建工具下载镜像，build.zigMirror 是编译工具链下载镜像。每一项都可以选不使用镜像（默认）、中国镜像，或填写自定义地址。构建因下载失败而停止时，会指出这些设置的位置。

项目检查

--lint 不打开界面，运行与问题面板相同的项目检查，结束时返回状态码。它不产出任何构建。

narraleaf-studio --lint /projects/my-game --lint-report /artifacts/lint.json

选项	取值	默认
`--lint`	项目目录，或最近打开过的项目名称	必填
`--lint-report`	写出报告的文件	不写报告
`--lint-user-data-dir`	本次运行使用的配置目录	已安装的配置
`--lint-plugin`	本次运行启用的插件，按名称或 id 指定，可重复	配置中已启用的插件

--lint-plugin 只接受 --lint-plugin=名称 写法。--lint 与 --build 不能写在同一条命令里；给了 --lint-* 选项却没给 --lint 会被拒绝。

检查使用项目自己的设置：设为关闭的规则被跳过，每条问题的级别就是其规则所设的级别。项目中有错误，或在中止构建的级别为警告及错误时有警告，运行以状态码 1 结束。次要警告与提示不会让运行失败。状态码 0 表示检查通过，2 与 4 的含义与构建相同。

每条问题在日志中打印为一行，包含位置、消息与规则 id。次要警告按 info 级别打印。

--lint-report 对每一种结果都写出一个 JSON 文件，记录结果、状态码、Studio 版本与完整日志。检查运行过时，其中的 lint 部分包含：

字段	内容
`counts`	各级别的问题数：`error`、`warning`、`minor`、`info`
`findings`	每条问题，带 `severity`、规则 `id`、`message`，有位置时还带 `location`
`rulesRun`	运行过的规则
`skipped`	项目中设为关闭的规则

次要警告的 severity 为 "minor"，计入 counts.minor。

对构建机的要求

所有目标在 Windows 和 macOS 上都能构建，但能产出哪些桌面格式由构建机的系统决定，与窗口里一致：

构建机	Windows	macOS	Linux
Windows	`zip`、`nsis`、`dir`	`zip`	`zip`、`appimage`
macOS	`zip`、`nsis`、`dir`	`zip`、`dmg`、`dir`	`zip`、`appimage`、`dir`

在 Windows 上，macOS 和 Linux 的包会直接写进压缩包：Windows 的文件夹存不下 macOS 应用所需的链接，也存不下 Linux 程序所需的权限，而磁盘映像只能在 macOS 上制作。构建机产不出的格式，会在打开项目之前就被拒绝。

在 Windows 上构建的 macOS 应用无法带上证书签名。玩家第一次打开时，要在系统设置 → 隐私与安全性中选择仍要打开，和打开任何未签名的 Mac 应用一样。用证书签名和公证仍然需要 Mac。

构建机不需要显示器，也不需要已登录的桌面会话，一个远程 shell 就够。

某个平台的首次构建会下载该平台需要的文件，比之后几次更慢。

关于构建窗口与其余构建设置，见运行与打包。

本页目录