fpack.yaml reference

Every key of fpack.yaml with type, default, targets and matching variable or flag.

fpack.yaml 参考

fpack.yaml 的每个键：类型、默认值、适用目标，以及对应的变量或参数。

This page is the complete reference. If you are looking for how to do something, start with the guides: names, versions and output, flavors and defines, secrets, hooks, or the platform tutorials.

Every key is optional. fpack looks for fpack.yaml in the project root (or --config FILE / FPACK_CONFIG). The file is read, validated and merged with FPACK_* variables and flags; see which setting wins.

Creating the file#

fpack init writes a file that lists every key, each with an English (--lang zh: Chinese) comment describing what it does, its allowed values, default, an example and the matching environment variable or flag, pre-filled with values detected in the project (application ID, flavors, version, team ID, Inno AppId…). Leave the keys you do not need commented out. Run it again later and it writes fpack.yaml.new and shows a diff; --force overwrites.

Validation#

Unknown keys (with "did you mean …"), type errors (line 12: android.signing.v1: expected true or false, got "maybe"), allowed values and ranges, conflicting combinations.
Files used by the selected targets are checked before building.
${VAR} and ${VAR:-default} are expanded on load in any value.
Editor completion: the first line of the generated file is # yaml-language-server: $schema=…, so VS Code (YAML extension) and JetBrains give completion, hover docs (English and Chinese) and validation. See JSON Schema.

A complete example#

# yaml-language-server: $schema=https://raw.githubusercontent.com/Matkurban/fpack/main/schema/fpack.schema.json
app:
  display_name: My App
  publisher: Example Inc             # default: CompanyName in windows/runner/Runner.rc
  homepage: https://example.com
  license: MIT

build:
  targets: [apk, aab, ipa, dmg]      # built by `fpack build` without targets
  flavor: prod
  dart_define_from_file: [config/prod.json]

output:
  dir: "dist/{version}{+build}"
  names: { exe: "{app}-setup-{version}", web: "{app}-web" }   # per-target names; {target} {date} also work
  checksum_algorithm: sha512         # SHA512SUMS

hooks:
  pre_build: [dart run build_runner build --delete-conflicting-outputs]
  post_package: { dmg: ['./scripts/upload.sh "$FPACK_ARTIFACT"'] }

android:
  split_per_abi: both
  signing:
    store_file: ~/keys/upload.jks
    store_password: ${FPACK_ANDROID_KEYSTORE_PASSWORD}
    key_alias: upload
    v4: true                         # any of v1–v4 re-signs with apksigner; v4 also writes the .idsig

ios:
  export_method: ad-hoc
  team_id: ABCDE12345                # fpack then generates ExportOptions.plist
  provisioning_profiles: { com.example.app: My App AdHoc }

macos:
  sign:
    identity: "Developer ID Application: Example Inc (ABCDE12345)"
    notary_profile: fpack-notary           # or notary_api_key/_id/_issuer, or notary_apple_id/_team_id/_password
  notarize:
    wait: true                       # false: submit without waiting (staple later with fpack notarize finish)
  dmg: { background: macos/dmg/bg.png, window_size: [660, 400], format: ULFO }
  pkg: { min_os: "11.0", postinstall: macos/installer/postinstall.sh }

windows:
  inno_setup: { languages: [zh-CN, en], privileges: ask, desktop_icon: checked }
  sign: { certificate: C:/certs/codesign.pfx, password: ${WINDOWS_CERT_PASSWORD} }
  msix: { publisher: "CN=Example Inc", capabilities: [internetClient] }

linux:
  categories: [Network, InstantMessaging]
  metainfo: linux/com.example.app.metainfo.xml
  deb: { depends: ["libgtk-3-0 | libgtk-3-0t64"], postinst: linux/postinst }
  rpm: { requires: [gtk3], license: MIT }

web:
  base_href: /app/
  source_maps: true

Hooks: see the hooks guide.

File name templates#

output.name and output.names.<target> accept these placeholders (output.dir only {app}, {version}, {build}, {flavor} and {mode}; the per-artifact ones are empty there); {-x} / {+x} add the separator only when the value is not empty:

Placeholder	Value
`{app}`	`app.name` (default: pubspec `name`)
`{version}` / `{build}`	build name / build number
`{flavor}`	the flavor (empty where Flutter does not use it)
`{platform}`	`android` , `ios` , `macos` , `windows` , `linux` , `web`
`{arch}`	`arm64-v8a`, `universal`, `x64`, …
`{variant}`	`setup`, `portable`, …
`{mode}`	empty for release, otherwise `profile` / `debug`
`{target}`	the target name
`{date}`	build date `YYYYMMDD`

Key reference#

Every key of fpack.yaml (generated from fpack's key registry – the same source as validation, the JSON Schema and fpack init).

`app`#

Application metadata used by installers and packages.

Key	Type	Default	Targets	Description
`app.name`	string	`pubspec name`	all	Base name of artifact files ({app} in output.name). Example: `xue_hua_im`
`app.display_name`	string	`macOS PRODUCT_NAME, else pubspec name`	exe, msix, pkg, deb, rpm, appimage, linux	Human-readable app name: installer title, Start menu, .desktop Name=. Example: `XueHua IM`
`app.description`	string	`pubspec description`	deb, rpm, appimage, msix	Short description: deb Description, rpm Summary, .desktop Comment=, msix description. Example: `A fast and secure messenger`
`app.publisher`	string	`CompanyName in windows/runner/Runner.rc`	exe, msix, deb, rpm	Company / author: Windows installer publisher, msix publisher display name, deb Maintainer fallback, rpm Vendor. Example: `XueHua Tech`
`app.identifier`	string	`Linux APPLICATION_ID, Android applicationId or iOS bundle id`	exe, msix, pkg, appimage	Reverse-DNS app id: Inno Setup AppId seed, msix identity name, pkg identifier fallback. Example: `com.xuehua.im`
`app.homepage`	url	—	exe, deb, rpm	Website: Inno Setup publisher URL, deb Homepage, rpm URL. Example: `https://xuehua.example.com`
`app.support_url`	url	`app.homepage`	exe	Support link (Windows "Apps & features"). Example: `https://xuehua.example.com/support`
`app.maintainer`	string	`app.publisher`	deb, rpm	"Name " for deb Maintainer and rpm Packager. Example: `XueHua Team <dev@xuehua.example.com>`
`app.copyright`	string	`© <year> <publisher>`	exe, deb, rpm	Copyright line: Inno Setup AppCopyright and version info, deb copyright file. Example: `© 2026 XueHua Tech`
`app.license`	string	`Proprietary`	rpm, deb	License (SPDX id): rpm License, deb copyright file. Example: `MIT`

`flutter`#

Flutter SDK selection.

Key	Type	Default	Targets	Env / flag	Description
`flutter.sdk`	path	`FLUTTER_ROOT, fvm, PATH`	all	`FPACK_FLUTTER` `--flutter`	Flutter SDK root to use. Example: `~/fvm/versions/stable`

`build`#

Options for every flutter build.

Key	Type	Default	Targets	Env / flag	Description
`build.targets`	list (or one string)	—	—		Targets built by `fpack build` without arguments. Aliases accepted by the command line (e.g. `bundle` , `ios` , `setup` ) work here too. Example: `[apk, aab, ipa, dmg]`
`build.mode`	`release` \	`profile` \	`debug`	`release`	all
`build.flavor`	string	—	apk, aab, ipa, macos, dmg, pkg	`FPACK_FLAVOR` `--flavor`	Flavor / Xcode scheme (--flavor); appears in file names as {flavor}. Example: `prod`
`build.target`	path	`lib/main.dart`	all	`FPACK_ENTRY` `-t, --target`	Entry point (flutter -t). Example: `lib/main_prod.dart`
`build.dart_define`	map or `KEY=VALUE` list	—	all	`--dart-define`	--dart-define values (map or list of KEY=VALUE). Example: `{API_URL: https://api.example.com}`
`build.dart_define_from_file`	list (or one string)	—	all	`--dart-define-from-file`	--dart-define-from-file files (.json or .env). Example: `[config/prod.json]`
`build.build_name`	string/number	`pubspec version before +`	all	`FPACK_BUILD_NAME` `--build-name`	Version name ({version}). Example: `1.2.0`
`build.build_number`	string/number	`pubspec version after +`	all	`FPACK_BUILD_NUMBER` `--build-number`	Build number ({build}). Example: `42`
`build.obfuscate`	bool	`false`	apk, aab, ipa, macos, dmg, pkg, windows, exe, msix, linux, deb, rpm, appimage, snap	`FPACK_OBFUSCATE` `--obfuscate`	Obfuscate Dart code; symbols go to split_debug_info (default /debug-info/). Example: `true`
`build.split_debug_info`	string	`<output>/debug-info/<platform> when obfuscating`	apk, aab, ipa, macos, dmg, pkg, windows, exe, msix, linux, deb, rpm, appimage, snap	`--split-debug-info`	Directory for Dart debug symbols (--split-debug-info). Example: `build/symbols`
`build.tree_shake_icons`	bool	`true`	all		false = --no-tree-shake-icons (keep all icon font glyphs). Example: `false`
`build.extra_args`	list (or one string)	—	all		Extra arguments for every flutter build (also: everything after -- on the command line). Example: `[--no-pub]`

`output`#

Where artifacts go and how they are named.

Key	Type	Default	Targets	Env / flag	Description
`output.dir`	string	`dist/{version}{+build}`	all	`FPACK_OUTPUT_DIR` `-o, --output`	Artifact directory (relative to the project). Placeholders: {app} {version} {build} {flavor} {mode}. Example: `"dist/{version}{+build}"`
`output.name`	string	`{app}{-flavor}-{version}{+build}-{platform}{-arch}{-variant}{-mode}`	all		File name template without extension. Placeholders: {app} {version} {build} {platform} {arch} {variant} {mode} {flavor} {target} {date}; {-x}/{+x} add the separator only when x is set. Example: `"{app}-{version}-{platform}{-arch}"`
`output.names`	map	—	all		Per-target file name templates (target → template), overriding output.name. Example: `{exe: "{app}-setup-{version}", web: "{app}-web"}`
`output.overwrite`	bool	`false`	all	`FPACK_OVERWRITE` `-f, --force`	Replace existing artifacts instead of stopping. Example: `true`
`output.checksums`	bool	`true`	all		Write a checksum file next to the artifacts. Example: `false`
`output.checksum_algorithm`	`sha256` \	`sha512`	`sha256`	all

`hooks`#

Shell commands run around the build (working directory: project root).

Key	Type	Default	Targets	Description
`hooks.pre_build`	list (or one string)	—	all	Commands run once before the first flutter build; a failure stops the build. Example: `[dart run build_runner build --delete-conflicting-outputs]`
`hooks.post_build`	list (or one string)	—	all	Commands run once after all targets (also after build failures, but not when every target already failed its checks); FPACK_ARTIFACTS lists the produced files (one per line), FPACK_SUCCESS is 1/0. Example: `[./scripts/upload.sh]`
`hooks.pre_package`	map: target → commands	—	all	Per target (target → commands), before its packaging steps; FPACK_TARGET is set. Example: `{apk: [./scripts/check_size.sh]}`
`hooks.post_package`	map: target → commands	—	all	Per target, after its artifacts exist; FPACK_ARTIFACT (first file) and FPACK_ARTIFACTS are set. Example: `{dmg: [./scripts/upload_dmg.sh "$FPACK_ARTIFACT"]}`

`android`#

Android: apk, aab.

Key	Type	Default	Targets	Env / flag	Description
`android.split_per_abi`	`false` \	`true` \	`both`	`false`	apk
`android.abis`	list (or one string)	`armeabi-v7a, arm64-v8a, x86_64`	apk, aab	`--abis`	Target ABIs (--target-platform). Example: `[arm64-v8a, armeabi-v7a]`
`android.project_args`	map	—	apk, aab		Gradle project properties (flutter -P key=value), readable in build.gradle with project.findProperty (e.g. to toggle minify/R8). Example: `{minify: "true"}`
`android.extra_args`	list (or one string)	—	apk, aab		Extra arguments for flutter build apk/appbundle. Example: `[--android-skip-build-dependency-validation]`

`android.signing`

Release signing, injected without editing Gradle files. Keep passwords in environment variables.

Key	Type	Default	Targets	Env / flag	Description
`android.signing.store_file`	path	`none (android/key.properties of the project is used)`	apk, aab	`FPACK_ANDROID_KEYSTORE`	Keystore file (.jks/.keystore). FPACK_ANDROID_KEYSTORE_BASE64 can provide it in CI. Example: `~/keys/upload.jks`
`android.signing.store_password`	string	—	apk, aab	`FPACK_ANDROID_KEYSTORE_PASSWORD`	Keystore password. Example: `${KEYSTORE_PASSWORD}`
`android.signing.key_alias`	string	—	apk, aab	`FPACK_ANDROID_KEY_ALIAS`	Key alias. Example: `upload`
`android.signing.key_password`	string	`store_password`	apk, aab	`FPACK_ANDROID_KEY_PASSWORD`	Key password. Example: `${KEY_PASSWORD}`
`android.signing.v1`	bool	`apksigner default (on when minSdk < 24)`	apk		APK signature scheme v1 (JAR signing, needed below Android 7). Setting any of v1-v4 makes fpack re-sign the APKs with apksigner using android.signing. Example: `true`
`android.signing.v2`	bool	`true`	apk		APK signature scheme v2 (Android 7+). Example: `true`
`android.signing.v3`	bool	`true`	apk		APK signature scheme v3 (Android 9+, key rotation). Example: `true`
`android.signing.v4`	bool	`false`	apk		APK signature scheme v4 (incremental install, Android 11+); writes .idsig next to the APK. Example: `true`

`ios`#

iOS: ipa. Setting any of team_id … export_options makes fpack generate ExportOptions.plist.

Key	Type	Default	Targets	Env / flag	Description
`ios.export_method`	`app-store-connect` \	`app-store` \	`release-testing` \	`ad-hoc` \	`development` \
`ios.export_options_plist`	path	—	ipa	`FPACK_IOS_EXPORT_OPTIONS_PLIST` `--export-options-plist`	Your own ExportOptions.plist; wins over every generated option below. Example: `ios/ExportOptions.plist`
`ios.codesign`	bool	`true`	ipa	`FPACK_IOS_CODESIGN` `--no-codesign`	false = unsigned IPA (Payload/ zip) for re-signing later. Example: `false`
`ios.team_id`	string	`DEVELOPMENT_TEAM of the Xcode project`	ipa		Apple team ID (teamID). Example: `ABCDE12345`
`ios.signing_style`	`automatic` \	`manual`	`automatic`	ipa
`ios.signing_certificate`	string	—	ipa		signingCertificate (manual signing), e.g. "Apple Distribution". Example: `Apple Distribution`
`ios.provisioning_profiles`	map	—	ipa		provisioningProfiles: bundle id → profile name or UUID (include extensions). Example: `{com.xuehua.im: XueHua AdHoc}`
`ios.upload_symbols`	bool	`true`	ipa		uploadSymbols for App Store Connect. Example: `false`
`ios.manage_app_version_and_build_number`	bool	`true`	ipa		manageAppVersionAndBuildNumber: let App Store Connect bump the build number. Example: `false`
`ios.destination`	`export` \	`upload`	`export`	ipa
`ios.thinning`	string	`<none>`	ipa		thinning for ad-hoc/development/enterprise exports. Example: `<thin-for-all-variants>`
`ios.strip_swift_symbols`	bool	`true`	ipa		stripSwiftSymbols. Example: `false`
`ios.export_options`	map (any)	—	ipa		Any other ExportOptions.plist keys (added as-is). Example: `{iCloudContainerEnvironment: Production}`
`ios.extra_args`	list (or one string)	—	ipa		Extra arguments for flutter build ipa. Example: `[--no-tree-shake-icons]`

`macos`#

macOS: macos (.app zip), dmg, pkg.

Key	Type	Default	Targets	Env / flag	Description
`macos.smoke_test`	bool	`false`	macos, dmg, pkg	`FPACK_MACOS_SMOKE_TEST` `--smoke-test`	After signing, launch the app, check that it is still running after smoke_test_seconds, then quit it (catches launch failures such as unauthorized entitlements). Example: `true`
`macos.smoke_test_seconds`	int	`5`	macos, dmg, pkg		How long the smoke test waits (1-300). Example: `10`
`macos.extra_args`	list (or one string)	—	macos, dmg, pkg		Extra arguments for flutter build macos. Example: `[--no-tree-shake-icons]`

`macos.sign`

Developer ID signing and notarization (only from this file, FPACK_MACOS_* and flags).

Key	Type	Default	Targets	Env / flag	Description
`macos.sign.enabled`	bool	`true when identity is set`	macos, dmg, pkg	`FPACK_MACOS_SIGN` `--sign / --no-sign`	Re-sign the .app with Developer ID (and sign the DMG). true without identity picks the first "Developer ID Application" identity. false (--no-sign) also disables pkg signing and notarization. Example: `true`
`macos.sign.identity`	string	—	macos, dmg, pkg	`FPACK_MACOS_SIGN_IDENTITY` `--sign-identity`	codesign identity for the app; setting it turns signing on. Example: `"Developer ID Application: Your Name (TEAMID)"`
`macos.sign.entitlements`	path	`macos/Runner/Release.entitlements`	macos, dmg, pkg		Entitlements used when re-signing the app. Example: `macos/Runner/Release.entitlements`
`macos.sign.hardened_runtime`	bool	`true`	macos, dmg, pkg		Sign with the hardened runtime (required for notarization). Example: `true`
`macos.sign.notarize`	bool	`true when a notary credential is set`	macos, dmg, pkg	`FPACK_MACOS_NOTARIZE` `--notarize / --no-notarize`	Notarize and staple the zip, DMG and signed pkg (uploads to Apple). Example: `true`
`macos.sign.notary_profile`	string	—	macos, dmg, pkg	`FPACK_MACOS_NOTARY_PROFILE` `--notary-profile`	Keychain profile from `xcrun notarytool store-credentials <name>` (recommended locally). Example: `NotaryProfile`
`macos.sign.notary_apple_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_APPLE_ID`	Apple ID for notarization (with notary_team_id + notary_password), instead of a profile. Example: `dev@example.com`
`macos.sign.notary_team_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_TEAM_ID`	Team ID for Apple ID notarization. Example: `ABCDE12345`
`macos.sign.notary_password`	string	—	macos, dmg, pkg	`FPACK_NOTARY_PASSWORD`	App-specific password for Apple ID notarization. Example: `${NOTARY_PASSWORD}`
`macos.sign.notary_api_key`	path	—	macos, dmg, pkg	`FPACK_NOTARY_API_KEY`	App Store Connect API key (.p8) for notarization (CI friendly). Example: `~/keys/AuthKey_ABC123.p8`
`macos.sign.notary_api_key_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_API_KEY_ID`	API key ID. Example: `ABC123DEF4`
`macos.sign.notary_api_issuer`	string	—	macos, dmg, pkg	`FPACK_NOTARY_API_ISSUER`	API issuer UUID (omit for individual keys). Example: `69a6de7e-…`
`macos.sign.installer_identity`	string	—	pkg	`FPACK_MACOS_INSTALLER_IDENTITY` `--installer-identity`	Signs the .pkg; a separate certificate from the app's "Developer ID Application". Unset = unsigned pkg. Example: `"Developer ID Installer: Your Name (TEAMID)"`
`macos.sign.provisioning_profile`	path	`Xcode's embedded profile is kept`	macos, dmg, pkg	`FPACK_MACOS_PROVISIONING_PROFILE` `--provisioning-profile`	Developer ID provisioning profile, copied to Contents/embedded.provisionprofile before signing. Required when the entitlements use restricted keys (aps-environment, iCloud, associated domains, keychain access groups, …). Example: `macos/XueHua.provisionprofile`
`macos.sign.provisioning_profiles`	map	—	macos, dmg, pkg		Profiles for nested bundles (app extensions, login items): bundle id → .provisionprofile path. Example: `{com.xuehua.im.share: macos/XueHuaShare.provisionprofile}`
`macos.sign.profile_check`	bool	`true`	macos, dmg, pkg	`FPACK_MACOS_PROFILE_CHECK`	Check provisioning profiles and restricted entitlements before signing (type Developer ID, team, app id, expiry, authorized entitlements) and refuse development profiles. false skips the checks. Example: `false`

`macos.notarize`

How fpack waits for Apple's notary service. Every submission is recorded in /NOTARIZATION.md and notarization.json with copy-paste commands.

Key	Type	Default	Targets	Env / flag	Description
`macos.notarize.wait`	bool	`true`	macos, dmg, pkg	`FPACK_NOTARIZE_WAIT` `--notarize-no-wait`	true: stay attached until Apple answers (shows elapsed time; Ctrl-C stops waiting, the submission continues at Apple). false: submit, write NOTARIZATION.md / notarization.json and finish with status "submitted"; later run `fpack notarize finish` to staple. Example: `false`

`macos.dmg`

Disk image layout. Window/icon layout needs create-dmg (brew install create-dmg).

Key	Type	Default	Targets	Env / flag	Description
`macos.dmg.tool`	`auto` \	`hdiutil` \	`create-dmg`	`auto`	dmg
`macos.dmg.volume_name`	string	`.app name`	dmg		Volume name shown when the DMG is mounted. Example: `XueHua IM`
`macos.dmg.volume_icon`	path	—	dmg		Volume icon (.icns). create-dmg. Example: `macos/dmg/volume.icns`
`macos.dmg.background`	path	—	dmg		Window background image. create-dmg. Example: `macos/dmg/background.png`
`macos.dmg.window_position`	`[x, y]`	`[200, 120]`	dmg		Window position [x, y]. create-dmg. Example: `[200, 120]`
`macos.dmg.window_size`	`[x, y]`	`[660, 400]`	dmg		Window size [width, height]. create-dmg. Example: `[660, 400]`
`macos.dmg.icon_size`	int	`128`	dmg		Icon size in the window. create-dmg. Example: `128`
`macos.dmg.app_position`	`[x, y]`	`[180, 190]`	dmg		Position of the app icon [x, y]. create-dmg. Example: `[180, 190]`
`macos.dmg.applications_position`	`[x, y]`	`[480, 190]`	dmg		Position of the Applications link [x, y]. create-dmg. Example: `[480, 190]`
`macos.dmg.format`	`UDZO` \	`UDBZ` \	`ULFO` \	`ULMO` \	`UDRO`
`macos.dmg.filesystem`	`HFS+` \	`APFS`	`HFS+`	dmg
`macos.dmg.license`	path	—	dmg		License agreement shown when the DMG is opened (.txt/.rtf). create-dmg. Example: `LICENSE.txt`

`macos.pkg`

Installer package (pkgbuild + productbuild).

Key	Type	Default	Targets	Description
`macos.pkg.identifier`	string	`macOS bundle id`	pkg	Package identifier (pkgutil --pkgs). Example: `com.xuehua.im`
`macos.pkg.version`	string	`build name`	pkg	Package version. Example: `1.2.0`
`macos.pkg.install_location`	string	`/Applications`	pkg	Absolute directory the app is installed into. Example: `/Applications`
`macos.pkg.title`	string	`.app name`	pkg	Installer window title. Example: `XueHua IM`
`macos.pkg.welcome`	path	—	pkg	Welcome page (.html/.rtf/.txt). Example: `macos/installer/welcome.html`
`macos.pkg.readme`	path	—	pkg	Read-me page (.html/.rtf/.txt). Example: `macos/installer/readme.html`
`macos.pkg.license`	path	—	pkg	License page the user must accept (.html/.rtf/.txt). Example: `macos/installer/license.rtf`
`macos.pkg.conclusion`	path	—	pkg	Conclusion page (.html/.rtf/.txt). Example: `macos/installer/done.html`
`macos.pkg.background`	path	—	pkg	Background image (light and dark mode). Example: `macos/installer/background.png`
`macos.pkg.min_os`	string	`MACOSX_DEPLOYMENT_TARGET of the project`	pkg	Minimum macOS version; Installer refuses older systems. Example: `10.15`
`macos.pkg.preinstall`	path	—	pkg	Script run before installing (made executable automatically). Example: `macos/installer/preinstall.sh`
`macos.pkg.postinstall`	path	—	pkg	Script run after installing. Example: `macos/installer/postinstall.sh`
`macos.pkg.relocatable`	bool	`false`	pkg	true = Installer updates a moved copy of the app wherever it is; false = always install_location. Example: `true`
`macos.pkg.require_restart`	bool	`false`	pkg	Ask the user to restart after installing. Example: `true`

`windows`#

Windows: windows (zip), exe (Inno Setup), msix.

Key	Type	Default	Targets	Env / flag	Description
`windows.extra_args`	list (or one string)	—	windows, exe, msix		Extra arguments for flutter build windows. Example: `[--no-tree-shake-icons]`

`windows.inno_setup`

Inno Setup installer (.exe).

Key	Type	Default	Targets	Env / flag	Description
`windows.inno_setup.app_id`	string	`stable GUID derived from app.identifier`	exe		AppId: keep it stable forever so upgrades replace the old install. Example: `8D3B5E6A-1C2D-4E5F-8A9B-0C1D2E3F4A5B`
`windows.inno_setup.script`	path	—	exe		Your own .iss script; fpack passes /DAppName /DAppVersion /DAppPublisher /DAppExeName /DSourceDir /DAppId /DAppURL. Example: `windows/installer.iss`
`windows.inno_setup.iscc`	path	`ISCC on PATH or in Program Files`	exe		Path to ISCC.exe. Example: `C:/Program Files (x86)/Inno Setup 6/ISCC.exe`
`windows.inno_setup.publisher`	string	`app.publisher`	exe		AppPublisher. Example: `XueHua Tech`
`windows.inno_setup.publisher_url`	url	`app.homepage`	exe		AppPublisherURL. Example: `https://xuehua.example.com`
`windows.inno_setup.support_url`	url	`app.support_url`	exe		AppSupportURL. Example: `https://xuehua.example.com/support`
`windows.inno_setup.updates_url`	url	—	exe		AppUpdatesURL. Example: `https://xuehua.example.com/download`
`windows.inno_setup.default_dir`	string	`{autopf}\<display name>`	exe		Default install directory (Inno constants allowed). Example: `'{autopf}\XueHua'`
`windows.inno_setup.group_name`	string	`display name`	exe		Start menu folder. Example: `XueHua`
`windows.inno_setup.desktop_icon`	`none` \	`unchecked` \	`checked`	`unchecked`	exe
`windows.inno_setup.run_after_install`	bool	`true`	exe		Offer "Launch " on the last page. Example: `false`
`windows.inno_setup.license_file`	path	—	exe		License page (.txt/.rtf). Example: `LICENSE.txt`
`windows.inno_setup.info_before`	path	—	exe		Information page before installing (.txt/.rtf). Example: `docs/before.txt`
`windows.inno_setup.info_after`	path	—	exe		Information page after installing (.txt/.rtf). Example: `docs/after.txt`
`windows.inno_setup.setup_icon`	path	`windows/runner/resources/app_icon.ico`	exe		Installer icon (.ico). Example: `windows/installer/setup.ico`
`windows.inno_setup.wizard_image`	path	—	exe		Large wizard image (.bmp/.png, 164×314 at 100%). Example: `windows/installer/wizard.bmp`
`windows.inno_setup.wizard_small_image`	path	—	exe		Small wizard image (.bmp/.png, 55×55). Example: `windows/installer/wizard-small.bmp`
`windows.inno_setup.wizard_style`	`modern` \	`classic`	`modern`	exe
`windows.inno_setup.languages`	list (or one string)	`[en]`	exe		Installer languages; the first is the default, the user picks one if several. zh-CN/zh-TW need Inno Setup 6.5+ (fpack ships the files otherwise). Known: en zh-CN zh-TW ja ko de fr es it pt-BR pt ru uk tr pl nl cs ar he. Example: `[zh-CN, en]`
`windows.inno_setup.privileges`	`user` \	`admin` \	`ask`	`ask`	exe
`windows.inno_setup.compression`	string	`lzma2/max`	exe		Compression (lzma2/max, lzma2/ultra64, zip, none …). Example: `lzma2/ultra64`
`windows.inno_setup.min_version`	string	`10.0`	exe		Minimum Windows version (MinVersion). Example: `10.0.17763`

`windows.sign`

Optional Authenticode signing with signtool: the app's .exe/.dll files (before zipping and packaging), the installer and the MSIX. Pick one certificate source: a .pfx file, the certificate store (thumbprint or subject) or a signtool plugin (dlib, e.g. Azure Trusted Signing).

Key	Type	Default	Targets	Env / flag	Description
`windows.sign.certificate`	path	—	windows, exe, msix	`FPACK_WINDOWS_CERTIFICATE`	Code signing certificate (.pfx). Setting it (or thumbprint) signs the app .exe, the installer and the MSIX. Example: `C:/certs/codesign.pfx`
`windows.sign.password`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERTIFICATE_PASSWORD`	Certificate password. Example: `${WINDOWS_CERT_PASSWORD}`
`windows.sign.thumbprint`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERT_THUMBPRINT`	SHA-1 thumbprint of a certificate in the Windows certificate store (/sha1), instead of a .pfx. Example: `1A2B3C…`
`windows.sign.subject`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERT_SUBJECT`	Subject name of a certificate in the store (/n), instead of a thumbprint. Example: `XueHua Tech`
`windows.sign.store`	string	`My`	windows, exe, msix		Certificate store name (/s) for thumbprint/subject. Example: `My`
`windows.sign.machine_store`	bool	`false (current user)`	windows, exe, msix		Use the local machine store (/sm) instead of the current user's. Example: `true`
`windows.sign.dlib`	path	—	windows, exe, msix	`FPACK_WINDOWS_SIGN_DLIB`	signtool plugin (/dlib) for cloud signing, e.g. Azure Trusted Signing; needs dlib_metadata. Example: `C:/tools/Azure.CodeSigning.Dlib.dll`
`windows.sign.dlib_metadata`	path	—	windows, exe, msix	`FPACK_WINDOWS_SIGN_DLIB_METADATA`	Metadata file for the dlib (/dmdf), e.g. the Trusted Signing account and profile. Example: `signing/metadata.json`
`windows.sign.timestamp_url`	url	`http://timestamp.digicert.com`	windows, exe, msix		RFC 3161 timestamp server (/tr, SHA-256). Example: `http://timestamp.sectigo.com`
`windows.sign.signtool`	path	`signtool on PATH or in the newest Windows SDK`	windows, exe, msix		Path to signtool.exe. Example: `C:/Program Files (x86)/Windows Kits/10/bin/10.0.26100.0/x64/signtool.exe`
`windows.sign.description`	string	`app.display_name`	windows, exe, msix		Description shown in the UAC prompt (/d). Example: `XueHua IM`
`windows.sign.url`	url	—	windows, exe, msix		More-information URL stored in the signature (/du). Example: `https://xuehua.example.com`
`windows.sign.files`	list (or one string)	`[".exe", ".dll"]`	windows, exe, msix		Files of the Flutter Release folder to sign before packaging (patterns without / match in every folder). Example: `[".exe", "plugins/.dll"]`
`windows.sign.verify`	bool	`true`	windows, exe, msix		Check signatures with signtool verify /pa; a failure (e.g. an untrusted test certificate) is a warning. Example: `false`

`windows.msix`

MSIX package (needs the msix dev_dependency). These keys override pubspec msix_config.

Key	Type	Default	Targets	Description
`windows.msix.display_name`	string	`app.display_name`	msix	Display name. Example: `XueHua IM`
`windows.msix.publisher_display_name`	string	`app.publisher`	msix	Publisher display name. Example: `XueHua Tech`
`windows.msix.identity_name`	string	`app.identifier`	msix	Package identity name. Example: `com.xuehua.im`
`windows.msix.publisher`	string	`from the certificate`	msix	Publisher (certificate subject); required for the Store. Example: `CN=XueHua Tech, O=XueHua Tech, C=CN`
`windows.msix.version`	string	`build name as a.b.c.0`	msix	MSIX version (a.b.c.d). Example: `1.2.0.0`
`windows.msix.logo`	path	`msix default / app icon`	msix	Logo image (≥ 400×400 PNG). Example: `windows/msix/logo.png`
`windows.msix.description`	string	`msix_config.description, else the pubspec description`	msix	Package description. The msix package reads it only from pubspec.yaml, so fpack prints the msix_config entry to add when this value differs. Example: `A fast and secure messenger`
`windows.msix.capabilities`	list (or one string)	—	msix	Capabilities. Example: `[internetClient, microphone, webcam]`
`windows.msix.languages`	list (or one string)	—	msix	Languages. Example: `[zh-cn, en-us]`
`windows.msix.file_extensions`	list (or one string)	—	msix	File extensions the app opens. Example: `[.xhim]`
`windows.msix.protocol_activation`	list (or one string)	—	msix	URL protocols that activate the app. Example: `[xuehua]`
`windows.msix.execution_alias`	string	—	msix	Command-line alias. Example: `xuehua`
`windows.msix.start_at_login`	bool	`false`	msix	Start the app at login. Example: `true`
`windows.msix.os_min_version`	string	`10.0.17763.0`	msix	Minimum Windows version. Example: `10.0.19041.0`
`windows.msix.store`	bool	`false`	msix	Build for the Microsoft Store (unsigned, Store signs it). Example: `true`
`windows.msix.sign`	bool	`true`	msix	Sign the MSIX (false requires publisher). Example: `false`
`windows.msix.certificate`	path	`windows.sign.certificate, else msix test certificate`	msix	Certificate (.pfx) for the MSIX. Example: `C:/certs/codesign.pfx`
`windows.msix.certificate_password`	string	`windows.sign.password`	msix	Certificate password. Example: `${WINDOWS_CERT_PASSWORD}`
`windows.msix.extra_args`	list (or one string)	—	msix	Extra arguments for dart run msix:create. Example: `[--trim-logo, "false"]`

`linux`#

Linux: linux (tar.gz), deb, rpm, appimage, snap.

Key	Type	Default	Targets	Description
`linux.package_name`	string	`app name, lowercase with dashes`	deb, rpm, appimage, snap	deb/rpm package name and command name in /usr/bin. Example: `xuehua-im`
`linux.prefix`	string	`/opt/<package_name>`	deb, rpm	Directory the app bundle is installed into. Example: `/usr/lib/xuehua-im`
`linux.icon`	path	`flutter_launcher_icons image, else web/icons/Icon-512.png`	deb, rpm, appimage, snap	PNG icon for menus and the AppImage. Example: `assets/icon/icon.png`
`linux.icon_sizes`	list of int	`[16, 32, 48, 64, 128, 256, 512]`	deb, rpm	hicolor icon sizes installed (resized from linux.icon; never upscaled). Example: `[48, 128, 256]`
`linux.categories`	list (or one string)	`[Utility]`	deb, rpm, appimage, snap	freedesktop.org menu categories (.desktop Categories=). Example: `[Network, InstantMessaging]`
`linux.generic_name`	string	—	deb, rpm, appimage, snap	.desktop GenericName=. Example: `Instant Messenger`
`linux.keywords`	list (or one string)	—	deb, rpm, appimage, snap	.desktop Keywords= (search terms). Example: `[chat, im, message]`
`linux.mime_types`	list (or one string)	—	deb, rpm, appimage, snap	.desktop MimeType= (files / URL schemes the app opens). Example: `[x-scheme-handler/xuehua]`
`linux.startup_wm_class`	string	`binary name (APPLICATION_ID on GTK)`	deb, rpm, appimage, snap	.desktop StartupWMClass= (groups windows with the launcher). Example: `xue_hua_im`
`linux.metainfo`	path	—	deb, rpm, appimage, snap	AppStream metainfo installed to /usr/share/metainfo (software centers). Example: `linux/packaging/com.xuehua.im.metainfo.xml`
`linux.appimagetool`	path	`appimagetool on PATH`	appimage	Path to appimagetool. Example: `~/.local/bin/appimagetool`
`linux.extra_args`	list (or one string)	—	linux, deb, rpm, appimage, snap	Extra arguments for flutter build linux. Example: `[--no-tree-shake-icons]`

`linux.deb`

Debian/Ubuntu package.

Key	Type	Default	Targets	Env / flag	Description
`linux.deb.depends`	list (or one string)	`[libgtk-3-0 \| libgtk-3-0t64]`	deb		Depends. Example: `[libgtk-3-0, libsecret-1-0]`
`linux.deb.recommends`	list (or one string)	—	deb		Recommends. Example: `[gnome-keyring]`
`linux.deb.suggests`	list (or one string)	—	deb		Suggests. Example: `[libnotify-bin]`
`linux.deb.conflicts`	list (or one string)	—	deb		Conflicts. Example: `[xuehua-im-beta]`
`linux.deb.section`	string	`utils`	deb		Section. Example: `net`
`linux.deb.priority`	`required` \	`important` \	`standard` \	`optional` \	`extra`
`linux.deb.preinst`	path	—	deb		Maintainer script run before unpacking. Example: `linux/packaging/preinst`
`linux.deb.postinst`	path	—	deb		Maintainer script run after installing. Example: `linux/packaging/postinst`
`linux.deb.prerm`	path	—	deb		Maintainer script run before removal. Example: `linux/packaging/prerm`
`linux.deb.postrm`	path	—	deb		Maintainer script run after removal. Example: `linux/packaging/postrm`

`linux.rpm`

Fedora/RHEL/openSUSE package.

Key	Type	Default	Targets	Description
`linux.rpm.requires`	list (or one string)	`[gtk3]`	rpm	Requires. Example: `[gtk3, libsecret]`
`linux.rpm.group`	string	`Applications/Internet`	rpm	Group. Example: `Applications/Communications`
`linux.rpm.license`	string	`app.license`	rpm	License. Example: `MIT`
`linux.rpm.pre`	path	—	rpm	%pre script. Example: `linux/packaging/pre.sh`
`linux.rpm.post`	path	—	rpm	%post script. Example: `linux/packaging/post.sh`
`linux.rpm.preun`	path	—	rpm	%preun script. Example: `linux/packaging/preun.sh`
`linux.rpm.postun`	path	—	rpm	%postun script. Example: `linux/packaging/postun.sh`

`linux.appimage`

AppImage.

Key	Type	Default	Targets	Env / flag	Description
`linux.appimage.update_information`	string	—	appimage		Embedded update information (AppImageUpdate). Example: `gh-releases-zsync\|xuehua\|im\|latest\|*x86_64.AppImage.zsync`
`linux.appimage.extra_args`	list (or one string)	—	appimage		Extra arguments for appimagetool. Example: `[--comp, zstd]`

`linux.snap`

Snap package (snapcraft). fpack generates snapcraft.yaml around the already built bundle (dump plugin), so Flutter is not rebuilt inside snapcraft.

Key	Type	Default	Targets	Env / flag	Description
`linux.snap.name`	string	`linux.package_name`	snap		Snap name (lowercase letters, digits and dashes, at most 40 characters); also the command name. Example: `xuehua-im`
`linux.snap.summary`	string	`app.description (shortened to 78 characters)`	snap		One-line summary, at most 78 characters. Example: `Fast and secure messenger`
`linux.snap.description`	string	`app.description`	snap		Long description shown in the Snap Store. Example: `XueHua IM keeps your conversations private.`
`linux.snap.base`	`core24` \	`core22`	`core24`	snap
`linux.snap.grade`	`stable` \	`devel`	`stable (devel with devmode)`	snap
`linux.snap.confinement`	`strict` \	`classic` \	`devmode`	`strict`	snap
`linux.snap.license`	string	`app.license`	snap		SPDX license expression. Example: `MIT`
`linux.snap.plugs`	list (or one string)	`[desktop, desktop-legacy, wayland, x11, opengl, audio-playback, network, home] (none with classic)`	snap		Interfaces the app plugs; [] for none. Example: `[network, home, removable-media]`
`linux.snap.extensions`	list (or one string)	`[gnome] (none with classic)`	snap		Snapcraft extensions: gnome provides GTK 3, fonts, themes and the desktop launcher. Example: `[gnome]`
`linux.snap.stage_packages`	list (or one string)	—	snap		Extra Ubuntu packages bundled into the snap (libraries your plugins need). Example: `[libsecret-1-0]`
`linux.snap.apps`	map	—	snap		Extra commands: app name → executable in the bundle. They get the same plugs and extensions. Example: `{helper: helper-tool}`
`linux.snap.desktop`	path	`generated from app and linux keys`	snap		Your own .desktop file (Icon=${SNAP}/meta/gui/ .png). Example: `linux/packaging/xuehua-im.desktop`
`linux.snap.template`	path	`generated`	snap		Your own snapcraft.yaml. fpack replaces {name} {version} {summary} {description} {base} {grade} {confinement} {license} {command} and stages the bundle at bundle/ and the icon/.desktop at snap/gui/. Example: `snap/snapcraft.yaml`
`linux.snap.build_mode`	`auto` \	`destructive` \	`lxd` \	`multipass`	`auto: destructive on a matching Ubuntu (24.04 for core24), else lxd`
`linux.snap.extra_args`	list (or one string)	—	snap		Extra arguments for snapcraft pack. Example: `[--verbosity, verbose]`

`web`#

Web: web (zip).

Key	Type	Default	Targets	Env / flag	Description
`web.base_href`	string	`index.html as is`	web	`--base-href`	; must start and end with /. Example: `/app/`
`web.wasm`	bool	`false`	web	`--wasm`	Compile to WebAssembly (with JS fallback). Example: `true`
`web.source_maps`	bool	`false`	web		Generate source maps. Example: `true`
`web.csp`	bool	`false`	web		No dynamic code generation (Content-Security-Policy). Example: `true`
`web.optimization_level`	int	`4`	web		dart2js / dart2wasm optimization level 0-4 (-O). Example: `2`
`web.static_assets_url`	url	—	web		Serve static assets from another domain (must end with /). Example: `https://cdn.example.com/app/`
`web.web_resources_cdn`	bool	`true`	web		false = bundle CanvasKit instead of loading it from the CDN. Example: `false`
`web.web_define`	map	—	web		--web-define template variables for web/index.html. Example: `{API_URL: https://api.example.com}`
`web.extra_args`	list (or one string)	—	web		Extra arguments for flutter build web. Example: `[--dump-info]`

本页是完整参考。如果你想知道怎么做某件事，请先看指南：名称、版本与输出、Flavor 与编译变量、密钥、钩子，或平台教程。

所有键都是可选的。fpack 在项目根目录查找 fpack.yaml（或 --config 文件 / FPACK_CONFIG）。文件会被读取、校验，并与 FPACK_* 变量和命令行参数合并，见哪个设置优先。

创建文件#

fpack init 会写出一个列出所有键的文件，每个键都带有英文（--lang zh 时为中文）注释，说明它的作用、允许的值、默认值、示例以及对应的环境变量或参数，并预填从项目里检测到的值（应用 ID、flavor、版本、团队 ID、Inno AppId…）。不需要的键保持注释状态即可。以后再次运行，它会写出 fpack.yaml.new 并显示差异；--force 覆盖。

校验#

未知的键（带“是不是想写 …”的提示）、类型错误（line 12: android.signing.v1: expected true or false, got "maybe"）、允许的值和范围、互相冲突的组合。
所选目标用到的文件会在构建前检查。
任何值里的 ${VAR} 和 ${VAR:-默认值} 会在加载时展开。
编辑器补全：生成文件的第一行是 # yaml-language-server: $schema=…，所以 VS Code（YAML 扩展）和 JetBrains 都能提供补全、悬停文档（中英文）和校验。见 JSON Schema。

完整示例#

# yaml-language-server: $schema=https://raw.githubusercontent.com/Matkurban/fpack/main/schema/fpack.schema.json
app:
  display_name: 雪花IM
  publisher: Example Inc             # 默认：windows/runner/Runner.rc 的 CompanyName
  homepage: https://example.com
  license: MIT

build:
  targets: [apk, aab, ipa, dmg]      # `fpack build` 不带目标时构建这些
  flavor: prod
  dart_define_from_file: [config/prod.json]

output:
  dir: "dist/{version}{+build}"
  names: { exe: "{app}-setup-{version}", web: "{app}-web" }   # 按目标单独命名；还可用 {target} {date}
  checksum_algorithm: sha512         # SHA512SUMS

hooks:
  pre_build: [dart run build_runner build --delete-conflicting-outputs]
  post_package: { dmg: ['./scripts/upload.sh "$FPACK_ARTIFACT"'] }

android:
  split_per_abi: both
  signing:
    store_file: ~/keys/upload.jks
    store_password: ${FPACK_ANDROID_KEYSTORE_PASSWORD}
    key_alias: upload
    v4: true                         # 设置 v1–v4 任意一项时用 apksigner 重新签名，v4 额外输出 .idsig

ios:
  export_method: ad-hoc
  team_id: ABCDE12345                # 设置后 fpack 自动生成 ExportOptions.plist
  provisioning_profiles: { com.example.app: My App AdHoc }

macos:
  sign:
    identity: "Developer ID Application: Example Inc (ABCDE12345)"
    notary_profile: fpack-notary           # 或 notary_api_key/_id/_issuer，或 notary_apple_id/_team_id/_password
  notarize:
    wait: true                       # false：提交后不等待（fpack notarize finish 稍后装订）
  dmg: { background: macos/dmg/bg.png, window_size: [660, 400], format: ULFO }
  pkg: { min_os: "11.0", postinstall: macos/installer/postinstall.sh }

windows:
  inno_setup: { languages: [zh-CN, en], privileges: ask, desktop_icon: checked }
  sign: { certificate: C:/certs/codesign.pfx, password: ${WINDOWS_CERT_PASSWORD} }
  msix: { publisher: "CN=Example Inc", capabilities: [internetClient] }

linux:
  categories: [Network, InstantMessaging]
  metainfo: linux/com.example.app.metainfo.xml
  deb: { depends: ["libgtk-3-0 | libgtk-3-0t64"], postinst: linux/postinst }
  rpm: { requires: [gtk3], license: MIT }

web:
  base_href: /app/
  source_maps: true

钩子：见钩子指南。

文件名模板#

output.name 和 output.names.<目标> 支持以下占位符（output.dir 只支持 {app}、{version}、{build}、{flavor}、{mode}，其余按产物而定的占位符在目录中为空）；{-x} / {+x} 只在值非空时才加上分隔符：

占位符	值
`{app}`	`app.name`（默认：pubspec 的 `name`）
`{version}` / `{build}`	版本号 / 构建号
`{flavor}`	flavor（Flutter 不使用 flavor 的平台为空）
`{platform}`	`android` 、 `ios` 、 `macos` 、 `windows` 、 `linux` 、 `web`
`{arch}`	`arm64-v8a`、`universal`、`x64` …
`{variant}`	`setup`、`portable` …
`{mode}`	release 时为空，否则为 `profile` / `debug`
`{target}`	目标名
`{date}`	构建日期 `YYYYMMDD`

键参考#

fpack.yaml 的全部键（由 fpack 的键注册表生成——与校验、JSON Schema、fpack init 同源）。

`app`#

应用信息：用于安装程序、软件包元数据。

键	类型	默认值	目标	说明
`app.name`	string	`pubspec 的 name`	全部	产物文件名前缀（output.name 中的 {app}）。示例：`xue_hua_im`
`app.display_name`	string	`macOS 的 PRODUCT_NAME，否则为 pubspec 的 name`	exe, msix, pkg, deb, rpm, appimage, linux	给人看的应用名：安装程序标题、开始菜单、.desktop 的 Name=。示例：`雪花IM`
`app.description`	string	`pubspec 的 description`	deb, rpm, appimage, msix	简短描述：deb 的 Description、rpm 的 Summary、.desktop 的 Comment=、msix 描述。示例：`快速、安全的即时通讯应用`
`app.publisher`	string	`windows/runner/Runner.rc 中的 CompanyName`	exe, msix, deb, rpm	公司 / 作者：Windows 安装程序发布者、msix 发布者显示名、deb Maintainer 的后备值、rpm Vendor。示例：`XueHua Tech`
`app.identifier`	string	`Linux APPLICATION_ID、Android applicationId 或 iOS bundle id`	exe, msix, pkg, appimage	反向域名格式的应用 ID：Inno Setup AppId 的种子、msix identity name、pkg identifier 的后备值。示例： `com.xuehua.im`
`app.homepage`	url	—	exe, deb, rpm	官网：Inno Setup 发布者网址、deb 的 Homepage、rpm 的 URL。示例：`https://xuehua.example.com`
`app.support_url`	url	`app.homepage`	exe	技术支持链接（Windows“应用和功能”中显示）。示例：`https://xuehua.example.com/support`
`app.maintainer`	string	`app.publisher`	deb, rpm	deb Maintainer 与 rpm Packager 字段，格式 “名字 <邮箱>”。示例： `XueHua Team <dev@xuehua.example.com>`
`app.copyright`	string	`© <年份> <发布者>`	exe, deb, rpm	版权信息：Inno Setup 的 AppCopyright 与版本信息、deb 的 copyright 文件。示例：`© 2026 XueHua Tech`
`app.license`	string	`Proprietary`	rpm, deb	许可证（SPDX 标识）：rpm 的 License、deb 的 copyright 文件。示例：`MIT`

`flutter`#

Flutter SDK 选择。

键	类型	默认值	目标	环境变量 / 参数	说明
`flutter.sdk`	path	`FLUTTER_ROOT、fvm、PATH 中的 flutter`	全部	`FPACK_FLUTTER` `--flutter`	使用的 Flutter SDK 根目录。示例：`~/fvm/versions/stable`

`build`#

所有 flutter build 共用的选项。

键	类型	默认值	目标	环境变量 / 参数	说明
`build.targets`	list（或单个字符串）	—	—		执行 `fpack build` 且不带目标时构建的目标。命令行接受的别名（如 `bundle` 、 `ios` 、 `setup` ）这里同样可用。示例： `[apk, aab, ipa, dmg]`
`build.mode`	`release` \	`profile` \	`debug`	`release`	全部
`build.flavor`	string	—	apk, aab, ipa, macos, dmg, pkg	`FPACK_FLAVOR` `--flavor`	flavor / Xcode scheme（--flavor）；文件名中的 {flavor}。示例：`prod`
`build.target`	path	`lib/main.dart`	全部	`FPACK_ENTRY` `-t, --target`	入口文件（flutter -t）。示例：`lib/main_prod.dart`
`build.dart_define`	map 或 `KEY=VALUE` 列表	—	全部	`--dart-define`	--dart-define 值（map 或 KEY=VALUE 列表）。示例：`{API_URL: https://api.example.com}`
`build.dart_define_from_file`	list（或单个字符串）	—	全部	`--dart-define-from-file`	--dart-define-from-file 文件（.json 或 .env）。示例：`[config/prod.json]`
`build.build_name`	string/number	`pubspec 版本号 + 之前的部分`	全部	`FPACK_BUILD_NAME` `--build-name`	版本名（{version}）。示例：`1.2.0`
`build.build_number`	string/number	`pubspec 版本号 + 之后的部分`	全部	`FPACK_BUILD_NUMBER` `--build-number`	构建号（{build}）。示例：`42`
`build.obfuscate`	bool	`false`	apk, aab, ipa, macos, dmg, pkg, windows, exe, msix, linux, deb, rpm, appimage, snap	`FPACK_OBFUSCATE` `--obfuscate`	混淆 Dart 代码；符号文件保存到 split_debug_info（默认 <输出目录>/debug-info/<平台>）。示例：`true`
`build.split_debug_info`	string	`混淆时为 <输出目录>/debug-info/<平台>`	apk, aab, ipa, macos, dmg, pkg, windows, exe, msix, linux, deb, rpm, appimage, snap	`--split-debug-info`	Dart 调试符号目录（--split-debug-info）。示例：`build/symbols`
`build.tree_shake_icons`	bool	`true`	全部		false 时传 --no-tree-shake-icons（保留全部图标字体字形）。示例：`false`
`build.extra_args`	list（或单个字符串）	—	全部		追加到每个 flutter build 的参数（命令行 -- 之后的参数同理）。示例：`[--no-pub]`

`output`#

产物输出目录与命名。

键	类型	默认值	目标	环境变量 / 参数	说明
`output.dir`	string	`dist/{version}{+build}`	全部	`FPACK_OUTPUT_DIR` `-o, --output`	产物目录（相对于项目）。占位符：{app} {version} {build} {flavor} {mode}。示例：`"dist/{version}{+build}"`
`output.name`	string	`{app}{-flavor}-{version}{+build}-{platform}{-arch}{-variant}{-mode}`	全部		文件名模板（不含扩展名）。占位符：{app} {version} {build} {platform} {arch} {variant} {mode} {flavor} {target} {date}；{-x}/{+x} 表示 x 非空时才加分隔符。示例： `"{app}-{version}-{platform}{-arch}"`
`output.names`	map	—	全部		按目标单独设置文件名模板（目标 → 模板），优先于 output.name。示例： `{exe: "{app}-setup-{version}", web: "{app}-web"}`
`output.overwrite`	bool	`false`	全部	`FPACK_OVERWRITE` `-f, --force`	已存在同名产物时覆盖，而不是停止。示例：`true`
`output.checksums`	bool	`true`	全部		在产物旁写入校验和文件。示例：`false`
`output.checksum_algorithm`	`sha256` \	`sha512`	`sha256`	全部

`hooks`#

构建前后执行的 shell 命令（工作目录：项目根目录）。

键	类型	默认值	目标	说明
`hooks.pre_build`	list（或单个字符串）	—	全部	第一次 flutter build 之前执行一次；失败则停止构建。示例： `[dart run build_runner build --delete-conflicting-outputs]`
`hooks.post_build`	list（或单个字符串）	—	全部	全部目标完成后执行一次（构建失败后也会执行，但所有目标都未通过构建前检查时跳过）；FPACK_ARTIFACTS 为产物列表（每行一个），FPACK_SUCCESS 为 1/0。示例： `[./scripts/upload.sh]`
`hooks.pre_package`	map：目标 → 命令列表	—	全部	按目标（目标 → 命令）在打包步骤之前执行；提供 FPACK_TARGET。示例：`{apk: [./scripts/check_size.sh]}`
`hooks.post_package`	map：目标 → 命令列表	—	全部	按目标在产物生成后执行；提供 FPACK_ARTIFACT（第一个产物）和 FPACK_ARTIFACTS。示例： `{dmg: [./scripts/upload_dmg.sh "$FPACK_ARTIFACT"]}`

`android`#

Android：apk、aab。

键	类型	默认值	目标	环境变量 / 参数	说明
`android.split_per_abi`	`false` \	`true` \	`both`	`false`	apk
`android.abis`	list（或单个字符串）	`armeabi-v7a、arm64-v8a、x86_64`	apk, aab	`--abis`	目标 ABI（--target-platform）。示例：`[arm64-v8a, armeabi-v7a]`
`android.project_args`	map	—	apk, aab		Gradle 项目属性（flutter -P key=value），build.gradle 中可用 project.findProperty 读取（例如开关 minify/R8）。示例： `{minify: "true"}`
`android.extra_args`	list（或单个字符串）	—	apk, aab		追加到 flutter build apk/appbundle 的参数。示例：`[--android-skip-build-dependency-validation]`

`android.signing`

发布签名：通过注入方式生效，不修改 Gradle 文件。密码请放在环境变量中。

键	类型	默认值	目标	环境变量 / 参数	说明
`android.signing.store_file`	path	`无（使用项目自己的 android/key.properties）`	apk, aab	`FPACK_ANDROID_KEYSTORE`	keystore 文件（.jks/.keystore）。CI 中可用 FPACK_ANDROID_KEYSTORE_BASE64 提供。示例： `~/keys/upload.jks`
`android.signing.store_password`	string	—	apk, aab	`FPACK_ANDROID_KEYSTORE_PASSWORD`	keystore 密码。示例：`${KEYSTORE_PASSWORD}`
`android.signing.key_alias`	string	—	apk, aab	`FPACK_ANDROID_KEY_ALIAS`	key 别名。示例：`upload`
`android.signing.key_password`	string	`store_password`	apk, aab	`FPACK_ANDROID_KEY_PASSWORD`	key 密码。示例：`${KEY_PASSWORD}`
`android.signing.v1`	bool	`apksigner 默认（minSdk < 24 时开启）`	apk		APK v1 签名（JAR 签名，Android 7 以下需要）。设置 v1-v4 任意一项时，fpack 会用 apksigner 和 android.signing 重新签名 APK。示例： `true`
`android.signing.v2`	bool	`true`	apk		APK v2 签名（Android 7+）。示例：`true`
`android.signing.v3`	bool	`true`	apk		APK v3 签名（Android 9+，支持密钥轮换）。示例：`true`
`android.signing.v4`	bool	`false`	apk		APK v4 签名（增量安装，Android 11+）；会在 APK 旁生成 .idsig。示例：`true`

`ios`#

iOS：ipa。设置 team_id … export_options 中任意一项时，fpack 会自动生成 ExportOptions.plist。

键	类型	默认值	目标	环境变量 / 参数	说明
`ios.export_method`	`app-store-connect` \	`app-store` \	`release-testing` \	`ad-hoc` \	`development` \
`ios.export_options_plist`	path	—	ipa	`FPACK_IOS_EXPORT_OPTIONS_PLIST` `--export-options-plist`	自己的 ExportOptions.plist；优先于下面所有生成选项。示例：`ios/ExportOptions.plist`
`ios.codesign`	bool	`true`	ipa	`FPACK_IOS_CODESIGN` `--no-codesign`	false：构建未签名 IPA（Payload/ 结构），用于之后重签名。示例：`false`
`ios.team_id`	string	`Xcode 工程中的 DEVELOPMENT_TEAM`	ipa		Apple 团队 ID（teamID）。示例：`ABCDE12345`
`ios.signing_style`	`automatic` \	`manual`	`automatic`	ipa
`ios.signing_certificate`	string	—	ipa		signingCertificate（手动签名），例如 "Apple Distribution"。示例：`Apple Distribution`
`ios.provisioning_profiles`	map	—	ipa		provisioningProfiles：bundle id → 描述文件名称或 UUID（扩展也要列出）。示例：`{com.xuehua.im: XueHua AdHoc}`
`ios.upload_symbols`	bool	`true`	ipa		uploadSymbols：是否上传符号表到 App Store Connect。示例：`false`
`ios.manage_app_version_and_build_number`	bool	`true`	ipa		manageAppVersionAndBuildNumber：是否由 App Store Connect 自动管理版本号/构建号。示例：`false`
`ios.destination`	`export` \	`upload`	`export`	ipa
`ios.thinning`	string	`<none>`	ipa		ad-hoc/development/enterprise 导出时的瘦身（thinning）选项。示例：`<thin-for-all-variants>`
`ios.strip_swift_symbols`	bool	`true`	ipa		stripSwiftSymbols。示例：`false`
`ios.export_options`	map (any)	—	ipa		其他任意 ExportOptions.plist 键（原样写入）。示例：`{iCloudContainerEnvironment: Production}`
`ios.extra_args`	list（或单个字符串）	—	ipa		追加到 flutter build ipa 的参数。示例：`[--no-tree-shake-icons]`

`macos`#

macOS：macos（.app zip）、dmg、pkg。

键	类型	默认值	目标	环境变量 / 参数	说明
`macos.smoke_test`	bool	`false`	macos, dmg, pkg	`FPACK_MACOS_SMOKE_TEST` `--smoke-test`	签名后启动 App，检查 smoke_test_seconds 秒后仍在运行，然后退出（可发现未授权 entitlements 等启动失败）。示例：`true`
`macos.smoke_test_seconds`	int	`5`	macos, dmg, pkg		启动测试的等待秒数（1-300）。示例：`10`
`macos.extra_args`	list（或单个字符串）	—	macos, dmg, pkg		追加到 flutter build macos 的参数。示例：`[--no-tree-shake-icons]`

`macos.sign`

Developer ID 签名与公证（只来自本文件、FPACK_MACOS_* 和命令行参数）。

键	类型	默认值	目标	环境变量 / 参数	说明
`macos.sign.enabled`	bool	`设置了 identity 时为 true`	macos, dmg, pkg	`FPACK_MACOS_SIGN` `--sign / --no-sign`	用 Developer ID 重新签名 .app（并签名 DMG）。为 true 但未设置 identity 时自动选用第一个 “Developer ID Application” 证书。false（--no-sign）同时关闭 pkg 签名与公证。示例： `true`
`macos.sign.identity`	string	—	macos, dmg, pkg	`FPACK_MACOS_SIGN_IDENTITY` `--sign-identity`	App 的 codesign 证书；设置后即启用签名。示例：`"Developer ID Application: Your Name (TEAMID)"`
`macos.sign.entitlements`	path	`macos/Runner/Release.entitlements`	macos, dmg, pkg		重新签名 App 时使用的 entitlements。示例：`macos/Runner/Release.entitlements`
`macos.sign.hardened_runtime`	bool	`true`	macos, dmg, pkg		使用 Hardened Runtime 签名（公证必需）。示例：`true`
`macos.sign.notarize`	bool	`设置了公证凭证时为 true`	macos, dmg, pkg	`FPACK_MACOS_NOTARIZE` `--notarize / --no-notarize`	公证并装订 zip、DMG 与已签名的 pkg（会上传到 Apple）。示例：`true`
`macos.sign.notary_profile`	string	—	macos, dmg, pkg	`FPACK_MACOS_NOTARY_PROFILE` `--notary-profile`	`xcrun notarytool store-credentials <名字>` 创建的钥匙串配置名（本地推荐）。示例： `NotaryProfile`
`macos.sign.notary_apple_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_APPLE_ID`	公证用 Apple ID（配合 notary_team_id + notary_password），替代钥匙串配置。示例：`dev@example.com`
`macos.sign.notary_team_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_TEAM_ID`	Apple ID 公证时的团队 ID。示例：`ABCDE12345`
`macos.sign.notary_password`	string	—	macos, dmg, pkg	`FPACK_NOTARY_PASSWORD`	Apple ID 公证用的 App 专用密码。示例：`${NOTARY_PASSWORD}`
`macos.sign.notary_api_key`	path	—	macos, dmg, pkg	`FPACK_NOTARY_API_KEY`	公证用 App Store Connect API 密钥（.p8，适合 CI）。示例：`~/keys/AuthKey_ABC123.p8`
`macos.sign.notary_api_key_id`	string	—	macos, dmg, pkg	`FPACK_NOTARY_API_KEY_ID`	API 密钥 ID。示例：`ABC123DEF4`
`macos.sign.notary_api_issuer`	string	—	macos, dmg, pkg	`FPACK_NOTARY_API_ISSUER`	API Issuer UUID（个人密钥可省略）。示例：`69a6de7e-…`
`macos.sign.installer_identity`	string	—	pkg	`FPACK_MACOS_INSTALLER_IDENTITY` `--installer-identity`	签名 .pkg 的证书，与 App 的 “Developer ID Application” 不同。不设置则 pkg 不签名。示例： `"Developer ID Installer: Your Name (TEAMID)"`
`macos.sign.provisioning_profile`	path	`保留 Xcode 嵌入的描述文件`	macos, dmg, pkg	`FPACK_MACOS_PROVISIONING_PROFILE` `--provisioning-profile`	Developer ID 描述文件，签名前复制为 Contents/embedded.provisionprofile。entitlements 使用受限键（aps-environment、iCloud、associated domains、keychain access groups 等）时必需。示例： `macos/XueHua.provisionprofile`
`macos.sign.provisioning_profiles`	map	—	macos, dmg, pkg		内嵌 bundle（App 扩展、登录项）的描述文件：bundle id → .provisionprofile 路径。示例： `{com.xuehua.im.share: macos/XueHuaShare.provisionprofile}`
`macos.sign.profile_check`	bool	`true`	macos, dmg, pkg	`FPACK_MACOS_PROFILE_CHECK`	签名前检查描述文件与受限 entitlements（Developer ID 类型、团队、App ID、有效期、已授权的 entitlements），并拒绝开发描述文件。false 跳过检查。示例： `false`

`macos.notarize`

如何等待 Apple 公证服务。每次提交都会记录到 <输出目录>/NOTARIZATION.md 和 notarization.json，其中有可直接复制的查询命令。

键	类型	默认值	目标	环境变量 / 参数	说明
`macos.notarize.wait`	bool	`true`	macos, dmg, pkg	`FPACK_NOTARIZE_WAIT` `--notarize-no-wait`	true：一直等待 Apple 返回结果（显示已等待时间；按 Ctrl-C 只是停止等待，Apple 端会继续处理）。false：提交后写入 NOTARIZATION.md / notarization.json 并结束，状态为 “submitted”；之后运行 `fpack notarize finish` 装订。示例： `false`

`macos.dmg`

DMG 磁盘镜像。窗口/图标布局需要 create-dmg（brew install create-dmg）。

键	类型	默认值	目标	环境变量 / 参数	说明
`macos.dmg.tool`	`auto` \	`hdiutil` \	`create-dmg`	`auto`	dmg
`macos.dmg.volume_name`	string	`.app 名称`	dmg		挂载 DMG 后显示的卷名。示例：`雪花IM`
`macos.dmg.volume_icon`	path	—	dmg		卷图标（.icns）。需要 create-dmg。示例：`macos/dmg/volume.icns`
`macos.dmg.background`	path	—	dmg		窗口背景图。需要 create-dmg。示例：`macos/dmg/background.png`
`macos.dmg.window_position`	`[x, y]`	`[200, 120]`	dmg		窗口位置 [x, y]。需要 create-dmg。示例：`[200, 120]`
`macos.dmg.window_size`	`[x, y]`	`[660, 400]`	dmg		窗口大小 [宽, 高]。需要 create-dmg。示例：`[660, 400]`
`macos.dmg.icon_size`	int	`128`	dmg		窗口中的图标大小。需要 create-dmg。示例：`128`
`macos.dmg.app_position`	`[x, y]`	`[180, 190]`	dmg		App 图标位置 [x, y]。需要 create-dmg。示例：`[180, 190]`
`macos.dmg.applications_position`	`[x, y]`	`[480, 190]`	dmg		“应用程序”快捷方式位置 [x, y]。需要 create-dmg。示例：`[480, 190]`
`macos.dmg.format`	`UDZO` \	`UDBZ` \	`ULFO` \	`ULMO` \	`UDRO`
`macos.dmg.filesystem`	`HFS+` \	`APFS`	`HFS+`	dmg
`macos.dmg.license`	path	—	dmg		打开 DMG 时显示的许可协议（.txt/.rtf）。需要 create-dmg。示例：`LICENSE.txt`

`macos.pkg`

安装包（pkgbuild + productbuild）。

键	类型	默认值	目标	说明
`macos.pkg.identifier`	string	`macOS 工程的 bundle id`	pkg	安装包标识（pkgutil --pkgs 中显示）。示例：`com.xuehua.im`
`macos.pkg.version`	string	`版本名`	pkg	安装包版本。示例：`1.2.0`
`macos.pkg.install_location`	string	`/Applications`	pkg	App 安装到的绝对路径目录。示例：`/Applications`
`macos.pkg.title`	string	`.app 名称`	pkg	安装器窗口标题。示例：`雪花IM`
`macos.pkg.welcome`	path	—	pkg	欢迎页（.html/.rtf/.txt）。示例：`macos/installer/welcome.html`
`macos.pkg.readme`	path	—	pkg	“请先阅读”页（.html/.rtf/.txt）。示例：`macos/installer/readme.html`
`macos.pkg.license`	path	—	pkg	用户必须同意的许可页（.html/.rtf/.txt）。示例：`macos/installer/license.rtf`
`macos.pkg.conclusion`	path	—	pkg	完成页（.html/.rtf/.txt）。示例：`macos/installer/done.html`
`macos.pkg.background`	path	—	pkg	背景图（浅色/深色模式都使用）。示例：`macos/installer/background.png`
`macos.pkg.min_os`	string	`工程的 MACOSX_DEPLOYMENT_TARGET`	pkg	最低 macOS 版本；低于此版本时安装器会拒绝安装。示例：`10.15`
`macos.pkg.preinstall`	path	—	pkg	安装前执行的脚本（自动设为可执行）。示例：`macos/installer/preinstall.sh`
`macos.pkg.postinstall`	path	—	pkg	安装后执行的脚本。示例：`macos/installer/postinstall.sh`
`macos.pkg.relocatable`	bool	`false`	pkg	true：App 被移动过时在原位置升级；false：总是安装到 install_location。示例：`true`
`macos.pkg.require_restart`	bool	`false`	pkg	安装完成后要求重启。示例：`true`

`windows`#

Windows：windows（zip）、exe（Inno Setup）、msix。

键	类型	默认值	目标	环境变量 / 参数	说明
`windows.extra_args`	list（或单个字符串）	—	windows, exe, msix		追加到 flutter build windows 的参数。示例：`[--no-tree-shake-icons]`

`windows.inno_setup`

Inno Setup 安装程序（.exe）。

键	类型	默认值	目标	环境变量 / 参数	说明
`windows.inno_setup.app_id`	string	`由 app.identifier 推导的固定 GUID`	exe		AppId：请永远保持不变，升级时才能覆盖旧版本。示例：`8D3B5E6A-1C2D-4E5F-8A9B-0C1D2E3F4A5B`
`windows.inno_setup.script`	path	—	exe		自定义 .iss 脚本；fpack 会传入 /DAppName /DAppVersion /DAppPublisher /DAppExeName /DSourceDir /DAppId /DAppURL。示例： `windows/installer.iss`
`windows.inno_setup.iscc`	path	`PATH 或 Program Files 中的 ISCC`	exe		ISCC.exe 路径。示例：`C:/Program Files (x86)/Inno Setup 6/ISCC.exe`
`windows.inno_setup.publisher`	string	`app.publisher`	exe		AppPublisher（发布者）。示例：`XueHua Tech`
`windows.inno_setup.publisher_url`	url	`app.homepage`	exe		AppPublisherURL（发布者网址）。示例：`https://xuehua.example.com`
`windows.inno_setup.support_url`	url	`app.support_url`	exe		AppSupportURL（支持网址）。示例：`https://xuehua.example.com/support`
`windows.inno_setup.updates_url`	url	—	exe		AppUpdatesURL（更新网址）。示例：`https://xuehua.example.com/download`
`windows.inno_setup.default_dir`	string	`{autopf}\<显示名>`	exe		默认安装目录（可用 Inno 常量）。示例：`'{autopf}\XueHua'`
`windows.inno_setup.group_name`	string	`显示名`	exe		开始菜单文件夹。示例：`XueHua`
`windows.inno_setup.desktop_icon`	`none` \	`unchecked` \	`checked`	`unchecked`	exe
`windows.inno_setup.run_after_install`	bool	`true`	exe		最后一页提供“运行 <应用>”选项。示例：`false`
`windows.inno_setup.license_file`	path	—	exe		许可协议页（.txt/.rtf）。示例：`LICENSE.txt`
`windows.inno_setup.info_before`	path	—	exe		安装前信息页（.txt/.rtf）。示例：`docs/before.txt`
`windows.inno_setup.info_after`	path	—	exe		安装后信息页（.txt/.rtf）。示例：`docs/after.txt`
`windows.inno_setup.setup_icon`	path	`windows/runner/resources/app_icon.ico`	exe		安装程序图标（.ico）。示例：`windows/installer/setup.ico`
`windows.inno_setup.wizard_image`	path	—	exe		向导大图（.bmp/.png，100% 缩放下 164×314）。示例：`windows/installer/wizard.bmp`
`windows.inno_setup.wizard_small_image`	path	—	exe		向导小图（.bmp/.png，55×55）。示例：`windows/installer/wizard-small.bmp`
`windows.inno_setup.wizard_style`	`modern` \	`classic`	`modern`	exe
`windows.inno_setup.languages`	list（或单个字符串）	`[en]`	exe		安装程序语言；第一个为默认，多个时让用户选择。zh-CN/zh-TW 需要 Inno Setup 6.5+（旧版本时 fpack 自带语言文件）。支持：en zh-CN zh-TW ja ko de fr es it pt-BR pt ru uk tr pl nl cs ar he。示例： `[zh-CN, en]`
`windows.inno_setup.privileges`	`user` \	`admin` \	`ask`	`ask`	exe
`windows.inno_setup.compression`	string	`lzma2/max`	exe		压缩方式（lzma2/max、lzma2/ultra64、zip、none 等）。示例：`lzma2/ultra64`
`windows.inno_setup.min_version`	string	`10.0`	exe		最低 Windows 版本（MinVersion）。示例：`10.0.17763`

`windows.sign`

可选的 Authenticode 签名（signtool）：应用的 .exe/.dll（在压缩和打包之前）、安装程序和 MSIX。选择一种证书来源：.pfx 文件、证书存储（指纹或主题名称）或 signtool 插件（dlib，如 Azure Trusted Signing）。

键	类型	默认值	目标	环境变量 / 参数	说明
`windows.sign.certificate`	path	—	windows, exe, msix	`FPACK_WINDOWS_CERTIFICATE`	代码签名证书（.pfx）。设置它（或 thumbprint）后会签名应用 .exe、安装程序和 MSIX。示例：`C:/certs/codesign.pfx`
`windows.sign.password`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERTIFICATE_PASSWORD`	证书密码。示例：`${WINDOWS_CERT_PASSWORD}`
`windows.sign.thumbprint`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERT_THUMBPRINT`	Windows 证书存储中证书的 SHA-1 指纹（/sha1），替代 .pfx。示例：`1A2B3C…`
`windows.sign.subject`	string	—	windows, exe, msix	`FPACK_WINDOWS_CERT_SUBJECT`	证书存储中证书的主题名称（/n），替代指纹。示例：`XueHua Tech`
`windows.sign.store`	string	`My`	windows, exe, msix		thumbprint/subject 使用的证书存储名称（/s）。示例：`My`
`windows.sign.machine_store`	bool	`false（当前用户）`	windows, exe, msix		使用本地计算机存储（/sm），而不是当前用户的存储。示例：`true`
`windows.sign.dlib`	path	—	windows, exe, msix	`FPACK_WINDOWS_SIGN_DLIB`	用于云签名的 signtool 插件（/dlib），如 Azure Trusted Signing；需同时设置 dlib_metadata。示例： `C:/tools/Azure.CodeSigning.Dlib.dll`
`windows.sign.dlib_metadata`	path	—	windows, exe, msix	`FPACK_WINDOWS_SIGN_DLIB_METADATA`	dlib 的元数据文件（/dmdf），如 Trusted Signing 的账户和证书配置。示例：`signing/metadata.json`
`windows.sign.timestamp_url`	url	`http://timestamp.digicert.com`	windows, exe, msix		RFC 3161 时间戳服务器（/tr，SHA-256）。示例：`http://timestamp.sectigo.com`
`windows.sign.signtool`	path	`PATH 或最新 Windows SDK 中的 signtool`	windows, exe, msix		signtool.exe 路径。示例： `C:/Program Files (x86)/Windows Kits/10/bin/10.0.26100.0/x64/signtool.exe`
`windows.sign.description`	string	`app.display_name`	windows, exe, msix		UAC 弹窗中显示的描述（/d）。示例：`XueHua IM`
`windows.sign.url`	url	—	windows, exe, msix		签名中记录的详细信息网址（/du）。示例：`https://xuehua.example.com`
`windows.sign.files`	list（或单个字符串）	`[".exe", ".dll"]`	windows, exe, msix		打包前要签名的 Flutter Release 文件夹中的文件（不含 / 的模式匹配所有子文件夹）。示例：`[".exe", "plugins/.dll"]`
`windows.sign.verify`	bool	`true`	windows, exe, msix		用 signtool verify /pa 校验签名；失败（例如不受信任的测试证书）只作为警告。示例：`false`

`windows.msix`

MSIX 包（需要 msix 开发依赖）。这些键会覆盖 pubspec 中的 msix_config。

键	类型	默认值	目标	说明
`windows.msix.display_name`	string	`app.display_name`	msix	显示名称。示例：`雪花IM`
`windows.msix.publisher_display_name`	string	`app.publisher`	msix	发布者显示名称。示例：`XueHua Tech`
`windows.msix.identity_name`	string	`app.identifier`	msix	包标识名称（Identity Name）。示例：`com.xuehua.im`
`windows.msix.publisher`	string	`取自证书`	msix	发布者（证书 Subject）；上架 Store 时必填。示例：`CN=XueHua Tech, O=XueHua Tech, C=CN`
`windows.msix.version`	string	`版本名补齐为 a.b.c.0`	msix	MSIX 版本（a.b.c.d）。示例：`1.2.0.0`
`windows.msix.logo`	path	`msix 默认 / 应用图标`	msix	Logo 图片（≥ 400×400 的 PNG）。示例：`windows/msix/logo.png`
`windows.msix.description`	string	`msix_config.description，否则为 pubspec 的 description`	msix	包描述。msix 包只从 pubspec.yaml 读取它，所以当这里的值不同时 fpack 会提示需要添加的 msix_config 条目。示例：`快速、安全的即时通讯应用`
`windows.msix.capabilities`	list（或单个字符串）	—	msix	能力声明（capabilities）。示例：`[internetClient, microphone, webcam]`
`windows.msix.languages`	list（或单个字符串）	—	msix	语言。示例：`[zh-cn, en-us]`
`windows.msix.file_extensions`	list（或单个字符串）	—	msix	应用可打开的文件扩展名。示例：`[.xhim]`
`windows.msix.protocol_activation`	list（或单个字符串）	—	msix	可激活应用的 URL 协议。示例：`[xuehua]`
`windows.msix.execution_alias`	string	—	msix	命令行别名。示例：`xuehua`
`windows.msix.start_at_login`	bool	`false`	msix	登录时自动启动。示例：`true`
`windows.msix.os_min_version`	string	`10.0.17763.0`	msix	最低 Windows 版本。示例：`10.0.19041.0`
`windows.msix.store`	bool	`false`	msix	为 Microsoft Store 构建（不签名，由 Store 签名）。示例：`true`
`windows.msix.sign`	bool	`true`	msix	是否签名 MSIX（false 时必须设置 publisher）。示例：`false`
`windows.msix.certificate`	path	`windows.sign.certificate，否则使用 msix 测试证书`	msix	签名 MSIX 用的证书（.pfx）。示例：`C:/certs/codesign.pfx`
`windows.msix.certificate_password`	string	`windows.sign.password`	msix	证书密码。示例：`${WINDOWS_CERT_PASSWORD}`
`windows.msix.extra_args`	list（或单个字符串）	—	msix	追加到 dart run msix:create 的参数。示例：`[--trim-logo, "false"]`

`linux`#

Linux：linux（tar.gz）、deb、rpm、appimage、snap。

键	类型	默认值	目标	说明
`linux.package_name`	string	`应用名转小写并用 - 连接`	deb, rpm, appimage, snap	deb/rpm 包名，以及 /usr/bin 中的命令名。示例：`xuehua-im`
`linux.prefix`	string	`/opt/<package_name>`	deb, rpm	应用文件的安装目录。示例：`/usr/lib/xuehua-im`
`linux.icon`	path	`flutter_launcher_icons 的图片，否则 web/icons/Icon-512.png`	deb, rpm, appimage, snap	菜单与 AppImage 使用的 PNG 图标。示例：`assets/icon/icon.png`
`linux.icon_sizes`	整数列表	`[16, 32, 48, 64, 128, 256, 512]`	deb, rpm	安装到 hicolor 主题的图标尺寸（由 linux.icon 缩放，不放大）。示例：`[48, 128, 256]`
`linux.categories`	list（或单个字符串）	`[Utility]`	deb, rpm, appimage, snap	freedesktop.org 菜单分类（.desktop 的 Categories=）。示例：`[Network, InstantMessaging]`
`linux.generic_name`	string	—	deb, rpm, appimage, snap	.desktop 的 GenericName=。示例：`Instant Messenger`
`linux.keywords`	list（或单个字符串）	—	deb, rpm, appimage, snap	.desktop 的 Keywords=（搜索关键词）。示例：`[chat, im, message]`
`linux.mime_types`	list（或单个字符串）	—	deb, rpm, appimage, snap	.desktop 的 MimeType=（可打开的文件类型 / URL 协议）。示例：`[x-scheme-handler/xuehua]`
`linux.startup_wm_class`	string	`可执行文件名`	deb, rpm, appimage, snap	.desktop 的 StartupWMClass=（让窗口与启动器图标归为一组）。示例：`xue_hua_im`
`linux.metainfo`	path	—	deb, rpm, appimage, snap	AppStream metainfo，安装到 /usr/share/metainfo（软件中心展示）。示例： `linux/packaging/com.xuehua.im.metainfo.xml`
`linux.appimagetool`	path	`PATH 中的 appimagetool`	appimage	appimagetool 路径。示例：`~/.local/bin/appimagetool`
`linux.extra_args`	list（或单个字符串）	—	linux, deb, rpm, appimage, snap	追加到 flutter build linux 的参数。示例：`[--no-tree-shake-icons]`

`linux.deb`

Debian/Ubuntu 软件包。

键	类型	默认值	目标	环境变量 / 参数	说明
`linux.deb.depends`	list（或单个字符串）	`[libgtk-3-0 \| libgtk-3-0t64]`	deb		Depends（依赖）。示例：`[libgtk-3-0, libsecret-1-0]`
`linux.deb.recommends`	list（或单个字符串）	—	deb		Recommends（推荐）。示例：`[gnome-keyring]`
`linux.deb.suggests`	list（或单个字符串）	—	deb		Suggests（建议）。示例：`[libnotify-bin]`
`linux.deb.conflicts`	list（或单个字符串）	—	deb		Conflicts（冲突）。示例：`[xuehua-im-beta]`
`linux.deb.section`	string	`utils`	deb		Section（分区）。示例：`net`
`linux.deb.priority`	`required` \	`important` \	`standard` \	`optional` \	`extra`
`linux.deb.preinst`	path	—	deb		解包前执行的维护脚本。示例：`linux/packaging/preinst`
`linux.deb.postinst`	path	—	deb		安装后执行的维护脚本。示例：`linux/packaging/postinst`
`linux.deb.prerm`	path	—	deb		卸载前执行的维护脚本。示例：`linux/packaging/prerm`
`linux.deb.postrm`	path	—	deb		卸载后执行的维护脚本。示例：`linux/packaging/postrm`

`linux.rpm`

Fedora/RHEL/openSUSE 软件包。

键	类型	默认值	目标	说明
`linux.rpm.requires`	list（或单个字符串）	`[gtk3]`	rpm	Requires（依赖）。示例：`[gtk3, libsecret]`
`linux.rpm.group`	string	`Applications/Internet`	rpm	Group（分组）。示例：`Applications/Communications`
`linux.rpm.license`	string	`app.license`	rpm	License（许可证）。示例：`MIT`
`linux.rpm.pre`	path	—	rpm	%pre 脚本。示例：`linux/packaging/pre.sh`
`linux.rpm.post`	path	—	rpm	%post 脚本。示例：`linux/packaging/post.sh`
`linux.rpm.preun`	path	—	rpm	%preun 脚本。示例：`linux/packaging/preun.sh`
`linux.rpm.postun`	path	—	rpm	%postun 脚本。示例：`linux/packaging/postun.sh`

`linux.appimage`

AppImage。

键	类型	默认值	目标	环境变量 / 参数	说明
`linux.appimage.update_information`	string	—	appimage		内嵌更新信息（供 AppImageUpdate 使用）。示例： `gh-releases-zsync\|xuehua\|im\|latest\|*x86_64.AppImage.zsync`
`linux.appimage.extra_args`	list（或单个字符串）	—	appimage		追加到 appimagetool 的参数。示例：`[--comp, zstd]`

`linux.snap`

Snap 包（snapcraft）。fpack 围绕已构建好的 bundle 生成 snapcraft.yaml（dump 插件），snapcraft 内不会再次构建 Flutter。

键	类型	默认值	目标	环境变量 / 参数	说明
`linux.snap.name`	string	`linux.package_name`	snap		Snap 名称（小写字母、数字和 -，最多 40 个字符），也是命令名。示例：`xuehua-im`
`linux.snap.summary`	string	`app.description（截断到 78 个字符）`	snap		一行简介，最多 78 个字符。示例：`快速、安全的即时通讯`
`linux.snap.description`	string	`app.description`	snap		在 Snap Store 中显示的详细描述。示例：`雪花 IM 保护你的聊天隐私。`
`linux.snap.base`	`core24` \	`core22`	`core24`	snap
`linux.snap.grade`	`stable` \	`devel`	`stable（devmode 时为 devel）`	snap
`linux.snap.confinement`	`strict` \	`classic` \	`devmode`	`strict`	snap
`linux.snap.license`	string	`app.license`	snap		SPDX 许可证表达式。示例：`MIT`
`linux.snap.plugs`	list（或单个字符串）	`[desktop, desktop-legacy, wayland, x11, opengl, audio-playback, network, home]（classic 时无）`	snap		应用连接的接口；[] 表示不需要。示例：`[network, home, removable-media]`
`linux.snap.extensions`	list（或单个字符串）	`[gnome]（classic 时无）`	snap		Snapcraft 扩展：gnome 提供 GTK 3、字体、主题与桌面启动器。示例：`[gnome]`
`linux.snap.stage_packages`	list（或单个字符串）	—	snap		额外打包进 snap 的 Ubuntu 软件包（插件需要的库）。示例：`[libsecret-1-0]`
`linux.snap.apps`	map	—	snap		额外命令：应用名 → bundle 中的可执行文件。使用相同的 plugs 和扩展。示例：`{helper: helper-tool}`
`linux.snap.desktop`	path	`根据 app 与 linux 键生成`	snap		自己的 .desktop 文件（Icon=${SNAP}/meta/gui/ .png）。示例： `linux/packaging/xuehua-im.desktop`
`linux.snap.template`	path	`自动生成`	snap		自己的 snapcraft.yaml。fpack 替换 {name} {version} {summary} {description} {base} {grade} {confinement} {license} {command}，并把 bundle 放在 bundle/、图标与 .desktop 放在 snap/gui/。示例： `snap/snapcraft.yaml`
`linux.snap.build_mode`	`auto` \	`destructive` \	`lxd` \	`multipass`	`auto：在匹配的 Ubuntu（core24 对应 24.04）上用 destructive，否则用 lxd`
`linux.snap.extra_args`	list（或单个字符串）	—	snap		追加到 snapcraft pack 的参数。示例：`[--verbosity, verbose]`

`web`#

Web：web（zip）。

键	类型	默认值	目标	环境变量 / 参数	说明
`web.base_href`	string	`保持 index.html 原样`	web	`--base-href`	；必须以 / 开头和结尾。示例：`/app/`
`web.wasm`	bool	`false`	web	`--wasm`	编译为 WebAssembly（带 JS 回退）。示例：`true`
`web.source_maps`	bool	`false`	web		生成 source map。示例：`true`
`web.csp`	bool	`false`	web		不动态生成代码（满足 CSP 限制）。示例：`true`
`web.optimization_level`	int	`4`	web		dart2js / dart2wasm 优化级别 0-4（-O）。示例：`2`
`web.static_assets_url`	url	—	web		从其他域名加载静态资源（必须以 / 结尾）。示例：`https://cdn.example.com/app/`
`web.web_resources_cdn`	bool	`true`	web		false：打包 CanvasKit，不从 CDN 加载。示例：`false`
`web.web_define`	map	—	web		--web-define：web/index.html 中的模板变量。示例：`{API_URL: https://api.example.com}`
`web.extra_args`	list（或单个字符串）	—	web		追加到 flutter build web 的参数。示例：`[--dump-info]`

fpack.yaml reference

fpack.yaml 参考

Creating the file#

Validation#

A complete example#

File name templates#

Key reference#

app#

flutter#

build#

output#

hooks#

android#

android.signing

ios#

macos#

macos.sign

macos.notarize

macos.dmg

macos.pkg

windows#

windows.inno_setup

windows.sign

windows.msix

linux#

linux.deb

linux.rpm

linux.appimage

linux.snap

web#

创建文件#

校验#

完整示例#

文件名模板#

键参考#

app#

flutter#

build#

output#

hooks#

android#

android.signing

ios#

macos#

macos.sign

macos.notarize

macos.dmg

macos.pkg

windows#

windows.inno_setup

windows.sign

windows.msix

linux#

linux.deb

linux.rpm

linux.appimage

linux.snap

web#

`app`#

`flutter`#

`build`#

`output`#

`hooks`#

`android`#

`android.signing`

`ios`#

`macos`#

`macos.sign`

`macos.notarize`

`macos.dmg`

`macos.pkg`

`windows`#

`windows.inno_setup`

`windows.sign`

`windows.msix`

`linux`#

`linux.deb`

`linux.rpm`

`linux.appimage`

`linux.snap`

`web`#

`app`#

`flutter`#

`build`#

`output`#

`hooks`#

`android`#

`android.signing`

`ios`#

`macos`#

`macos.sign`

`macos.notarize`

`macos.dmg`

`macos.pkg`

`windows`#

`windows.inno_setup`

`windows.sign`

`windows.msix`

`linux`#

`linux.deb`

`linux.rpm`

`linux.appimage`

`linux.snap`

`web`#