Logofpack

Environment variables

All FPACK_* variables, the variables fpack reads, and output language and color rules.

环境变量

所有 FPACK_* 变量以及 fpack 读取的其他变量。

Environment variables sit between flags and fpack.yaml in precedence: a flag beats a variable, a variable beats the file. This page lists every variable fpack reads, grouped by purpose. For how to use them for secrets, see Secrets and variables.

Variables that map to fpack.yaml keys#

Generated from the key registry. Any value in fpack.yaml can also reference arbitrary variables with ${VAR} / ${VAR:-default}.

Variablefpack.yaml keyTypeDescription
FPACK_FLUTTER flutter.sdk path Flutter SDK root to use.
FPACK_MODE build.mode release \ profile \
FPACK_FLAVOR build.flavor string Flavor / Xcode scheme (--flavor); appears in file names as {flavor}.
FPACK_ENTRY build.target path Entry point (flutter -t).
FPACK_BUILD_NAME build.build_name string/number Version name ({version}).
FPACK_BUILD_NUMBER build.build_number string/number Build number ({build}).
FPACK_OBFUSCATE build.obfuscate bool Obfuscate Dart code; symbols go to split_debug_info (default /debug-info/).
FPACK_OUTPUT_DIR output.dir string Artifact directory (relative to the project). Placeholders: {app} {version} {build} {flavor} {mode}.
FPACK_OVERWRITE output.overwrite bool Replace existing artifacts instead of stopping.
FPACK_SPLIT_PER_ABI android.split_per_abi false \ true \
FPACK_ANDROID_KEYSTORE android.signing.store_file path Keystore file (.jks/.keystore). FPACK_ANDROID_KEYSTORE_BASE64 can provide it in CI.
FPACK_ANDROID_KEYSTORE_PASSWORD android.signing.store_password string Keystore password.
FPACK_ANDROID_KEY_ALIAS android.signing.key_alias string Key alias.
FPACK_ANDROID_KEY_PASSWORD android.signing.key_password string Key password.
FPACK_IOS_EXPORT_METHOD ios.export_method app-store-connect \ app-store \
FPACK_IOS_EXPORT_OPTIONS_PLIST ios.export_options_plist path Your own ExportOptions.plist; wins over every generated option below.
FPACK_IOS_CODESIGN ios.codesign bool false = unsigned IPA (Payload/ zip) for re-signing later.
FPACK_MACOS_SIGN macos.sign.enabled bool 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.
FPACK_MACOS_SIGN_IDENTITY macos.sign.identity string codesign identity for the app; setting it turns signing on.
FPACK_MACOS_NOTARIZE macos.sign.notarize bool Notarize and staple the zip, DMG and signed pkg (uploads to Apple).
FPACK_MACOS_NOTARY_PROFILE macos.sign.notary_profile string Keychain profile from xcrun notarytool store-credentials <name> (recommended locally).
FPACK_NOTARY_APPLE_ID macos.sign.notary_apple_id string Apple ID for notarization (with notary_team_id + notary_password), instead of a profile.
FPACK_NOTARY_TEAM_ID macos.sign.notary_team_id string Team ID for Apple ID notarization.
FPACK_NOTARY_PASSWORD macos.sign.notary_password string App-specific password for Apple ID notarization.
FPACK_NOTARY_API_KEY macos.sign.notary_api_key path App Store Connect API key (.p8) for notarization (CI friendly).
FPACK_NOTARY_API_KEY_ID macos.sign.notary_api_key_id string API key ID.
FPACK_NOTARY_API_ISSUER macos.sign.notary_api_issuer string API issuer UUID (omit for individual keys).
FPACK_MACOS_INSTALLER_IDENTITY macos.sign.installer_identity string Signs the .pkg; a separate certificate from the app's "Developer ID Application". Unset = unsigned pkg.
FPACK_MACOS_PROVISIONING_PROFILE macos.sign.provisioning_profile path 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, …).
FPACK_MACOS_PROFILE_CHECK macos.sign.profile_check bool 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.
FPACK_NOTARIZE_WAIT macos.notarize.wait bool 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.
FPACK_MACOS_SMOKE_TEST macos.smoke_test bool 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).
FPACK_DMG_TOOL macos.dmg.tool auto \ hdiutil \
FPACK_WINDOWS_CERTIFICATE windows.sign.certificate path Code signing certificate (.pfx). Setting it (or thumbprint) signs the app .exe, the installer and the MSIX.
FPACK_WINDOWS_CERTIFICATE_PASSWORD windows.sign.password string Certificate password.
FPACK_WINDOWS_CERT_THUMBPRINT windows.sign.thumbprint string SHA-1 thumbprint of a certificate in the Windows certificate store (/sha1), instead of a .pfx.
FPACK_WINDOWS_CERT_SUBJECT windows.sign.subject string Subject name of a certificate in the store (/n), instead of a thumbprint.
FPACK_WINDOWS_SIGN_DLIB windows.sign.dlib path signtool plugin (/dlib) for cloud signing, e.g. Azure Trusted Signing; needs dlib_metadata.
FPACK_WINDOWS_SIGN_DLIB_METADATA windows.sign.dlib_metadata path Metadata file for the dlib (/dmdf), e.g. the Trusted Signing account and profile.
FPACK_SNAP_BUILD_MODE linux.snap.build_mode auto \ destructive \

Variables by purpose#

VariableEffect
FPACK_FLUTTERFlutter SDK path
FPACK_CONFIGconfiguration file path
FPACK_MODE FPACK_FLAVOR FPACK_ENTRY FPACK_BUILD_NAME FPACK_BUILD_NUMBER build parameters
FPACK_OUTPUT_DIR FPACK_OVERWRITE FPACK_SPLIT_PER_ABI FPACK_OBFUSCATE output / Android / obfuscation
FPACK_ANDROID_KEYSTORE FPACK_ANDROID_KEYSTORE_BASE64 FPACK_ANDROID_KEYSTORE_PASSWORD FPACK_ANDROID_KEY_ALIAS FPACK_ANDROID_KEY_PASSWORD Android signing
FPACK_IOS_EXPORT_METHOD FPACK_IOS_EXPORT_OPTIONS_PLIST FPACK_IOS_CODESIGN iOS export
FPACK_MACOS_SIGN FPACK_MACOS_SIGN_IDENTITY FPACK_MACOS_INSTALLER_IDENTITY FPACK_MACOS_NOTARIZE FPACK_MACOS_NOTARY_PROFILE FPACK_NOTARIZE_WAIT FPACK_MACOS_PROVISIONING_PROFILE FPACK_MACOS_PROFILE_CHECK FPACK_MACOS_SMOKE_TEST FPACK_DMG_TOOL macOS
FPACK_NOTARY_APPLE_ID FPACK_NOTARY_TEAM_ID FPACK_NOTARY_PASSWORD FPACK_NOTARY_API_KEY FPACK_NOTARY_API_KEY_ID FPACK_NOTARY_API_ISSUER macOS notary credentials (Apple ID / API key)
FPACK_WINDOWS_CERTIFICATE FPACK_WINDOWS_CERTIFICATE_PASSWORD FPACK_WINDOWS_CERT_THUMBPRINT FPACK_WINDOWS_CERT_SUBJECT FPACK_WINDOWS_SIGN_DLIB FPACK_WINDOWS_SIGN_DLIB_METADATA Windows code signing (.pfx, certificate store, or a signtool dlib such as Azure Trusted Signing)
FPACK_LANG zh / en (default: the OS language – see Output language )
NO_COLOR / FPACK_NO_COLOR / FORCE_COLOR colors
FPACK_COREuse this native core binary (development)
FPACK_HOMEcore cache directory
FPACK_REBUILD=1 build the core with local Go first (after changing the Go sources)
FPACK_GO the Go used for the fallback build (none disables local builds)
FPACK_NO_DOWNLOAD=1 / FPACK_DOWNLOAD_URL never download (build locally) / download mirror (intranet); see how the launcher finds the native core

Output language#

fpack (the Go core and the Dart launcher) speaks Chinese when your operating system's language is Chinese (any zh variant: Simplified, Traditional, Hong Kong…) and English otherwise. Everything follows it: messages, help, doctor / list output, error hints, the comments of the fpack.yaml written by fpack init, and NOTARIZATION.md.

Precedence (first match wins):

  1. --lang zh|en
  2. FPACK_LANG=zh|en
  3. the operating system language:
    • macOS: the first language in System Settings → General → Language & Region (defaults read -g AppleLanguages), then AppleLocale. Terminal usually sets LANG from the region (often en_US.UTF-8 even with a Chinese UI), so LANG / LANGUAGE are only used if that lookup fails; an explicit LC_ALL or LC_MESSAGES still wins. The result is cached in ~/Library/Caches/fpack/os-language and refreshed when the system preferences change.
    • Windows: the user's display language (GetUserDefaultUILanguage, no subprocess); LANG set by Git Bash/MSYS is ignored, an explicit LC_ALL / LC_MESSAGES still wins.
    • Linux and others: LC_ALL, LC_MESSAGES, LANGUAGE (first entry), LANG; C / POSIX are skipped.

Other variables fpack reads#

VariableUsed for
FLUTTER_ROOT, FVM_CACHE_PATH finding the Flutter SDK (after --flutter , FPACK_FLUTTER , flutter.sdk and the project's FVM link)
ANDROID_HOME / ANDROID_SDK_ROOT Android SDK tools ( apksigner ), after flutter config --android-sdk and before the default install folders (Flutter's own order)
JAVA_HOME keytool / Java version check, after flutter config --jdk-dir and Android Studio's bundled JDK, before PATH
XDG_CONFIG_HOME, APPDATA where Flutter's settings file is read from (for --android-sdk / --jdk-dir)
LOCALAPPDATA, ProgramFiles, ProgramFiles(x86) Windows: default locations of the Android SDK, Inno Setup, FVM and Flutter
LC_ALL, LC_MESSAGES, LANGUAGE, LANG output language (see above)
NO_COLOR, FPACK_NO_COLOR, TERM=dumb, FORCE_COLOR colors; TERM=dumb also turns off spinners
COLUMNStable width when the terminal size is unknown
XDG_CACHE_HOME launcher: cache root on Linux (FPACK_HOME overrides it)

Variables fpack sets for hooks#

fpack passes these to hooks; they are outputs, not settings.

VariableValue
FPACK_PROJECT_ROOTthe project directory
FPACK_OUTPUT_DIRthe artifact directory
FPACK_VERSION, FPACK_BUILD_NUMBER version name and build number
FPACK_MODE, FPACK_FLAVORbuild mode and flavor
FPACK_TARGET the target (pre_package / post_package)
FPACK_ARTIFACT, FPACK_ARTIFACTS artifacts (post_package, post_build)
FPACK_SUCCESS 1 or 0 (post_build)

环境变量在优先级中位于命令行参数和 fpack.yaml 之间:参数覆盖变量,变量覆盖文件。本页按用途列出 fpack 读取的每个变量。如何用它们保管密钥,见密钥与环境变量。

对应 fpack.yaml 键的变量#

由键注册表生成。它们覆盖 fpack.yaml,又会被命令行参数覆盖。fpack.yaml 中的任何值也都可以用 ${VAR} / ${VAR:-默认值} 引用任意环境变量。

变量对应 fpack.yaml类型说明
FPACK_FLUTTER flutter.sdk path 使用的 Flutter SDK 根目录。
FPACK_MODE build.mode release \ profile \
FPACK_FLAVOR build.flavor string flavor / Xcode scheme(--flavor);文件名中的 {flavor}。
FPACK_ENTRY build.target path 入口文件(flutter -t)。
FPACK_BUILD_NAME build.build_name string/number 版本名({version})。
FPACK_BUILD_NUMBER build.build_number string/number 构建号({build})。
FPACK_OBFUSCATE build.obfuscate bool 混淆 Dart 代码;符号文件保存到 split_debug_info(默认 <输出目录>/debug-info/<平台>)。
FPACK_OUTPUT_DIR output.dir string 产物目录(相对于项目)。占位符:{app} {version} {build} {flavor} {mode}。
FPACK_OVERWRITE output.overwrite bool 已存在同名产物时覆盖,而不是停止。
FPACK_SPLIT_PER_ABI android.split_per_abi false \ true \
FPACK_ANDROID_KEYSTORE android.signing.store_file path keystore 文件(.jks/.keystore)。CI 中可用 FPACK_ANDROID_KEYSTORE_BASE64 提供。
FPACK_ANDROID_KEYSTORE_PASSWORD android.signing.store_password string keystore 密码。
FPACK_ANDROID_KEY_ALIAS android.signing.key_alias string key 别名。
FPACK_ANDROID_KEY_PASSWORD android.signing.key_password string key 密码。
FPACK_IOS_EXPORT_METHOD ios.export_method app-store-connect \ app-store \
FPACK_IOS_EXPORT_OPTIONS_PLIST ios.export_options_plist path 自己的 ExportOptions.plist;优先于下面所有生成选项。
FPACK_IOS_CODESIGN ios.codesign bool false:构建未签名 IPA(Payload/ 结构),用于之后重签名。
FPACK_MACOS_SIGN macos.sign.enabled bool 用 Developer ID 重新签名 .app(并签名 DMG)。为 true 但未设置 identity 时自动选用第一个 “Developer ID Application” 证书。false(--no-sign)同时关闭 pkg 签名与公证。
FPACK_MACOS_SIGN_IDENTITY macos.sign.identity string App 的 codesign 证书;设置后即启用签名。
FPACK_MACOS_NOTARIZE macos.sign.notarize bool 公证并装订 zip、DMG 与已签名的 pkg(会上传到 Apple)。
FPACK_MACOS_NOTARY_PROFILE macos.sign.notary_profile string xcrun notarytool store-credentials <名字> 创建的钥匙串配置名(本地推荐)。
FPACK_NOTARY_APPLE_ID macos.sign.notary_apple_id string 公证用 Apple ID(配合 notary_team_id + notary_password),替代钥匙串配置。
FPACK_NOTARY_TEAM_ID macos.sign.notary_team_id string Apple ID 公证时的团队 ID。
FPACK_NOTARY_PASSWORD macos.sign.notary_password string Apple ID 公证用的 App 专用密码。
FPACK_NOTARY_API_KEY macos.sign.notary_api_key path 公证用 App Store Connect API 密钥(.p8,适合 CI)。
FPACK_NOTARY_API_KEY_ID macos.sign.notary_api_key_id string API 密钥 ID。
FPACK_NOTARY_API_ISSUER macos.sign.notary_api_issuer string API Issuer UUID(个人密钥可省略)。
FPACK_MACOS_INSTALLER_IDENTITY macos.sign.installer_identity string 签名 .pkg 的证书,与 App 的 “Developer ID Application” 不同。不设置则 pkg 不签名。
FPACK_MACOS_PROVISIONING_PROFILE macos.sign.provisioning_profile path Developer ID 描述文件,签名前复制为 Contents/embedded.provisionprofile。entitlements 使用受限键(aps-environment、iCloud、associated domains、keychain access groups 等)时必需。
FPACK_MACOS_PROFILE_CHECK macos.sign.profile_check bool 签名前检查描述文件与受限 entitlements(Developer ID 类型、团队、App ID、有效期、已授权的 entitlements),并拒绝开发描述文件。false 跳过检查。
FPACK_NOTARIZE_WAIT macos.notarize.wait bool true:一直等待 Apple 返回结果(显示已等待时间;按 Ctrl-C 只是停止等待,Apple 端会继续处理)。false:提交后写入 NOTARIZATION.md / notarization.json 并结束,状态为 “submitted”;之后运行 fpack notarize finish 装订。
FPACK_MACOS_SMOKE_TEST macos.smoke_test bool 签名后启动 App,检查 smoke_test_seconds 秒后仍在运行,然后退出(可发现未授权 entitlements 等启动失败)。
FPACK_DMG_TOOL macos.dmg.tool auto \ hdiutil \
FPACK_WINDOWS_CERTIFICATE windows.sign.certificate path 代码签名证书(.pfx)。设置它(或 thumbprint)后会签名应用 .exe、安装程序和 MSIX。
FPACK_WINDOWS_CERTIFICATE_PASSWORD windows.sign.password string 证书密码。
FPACK_WINDOWS_CERT_THUMBPRINT windows.sign.thumbprint string Windows 证书存储中证书的 SHA-1 指纹(/sha1),替代 .pfx。
FPACK_WINDOWS_CERT_SUBJECT windows.sign.subject string 证书存储中证书的主题名称(/n),替代指纹。
FPACK_WINDOWS_SIGN_DLIB windows.sign.dlib path 用于云签名的 signtool 插件(/dlib),如 Azure Trusted Signing;需同时设置 dlib_metadata。
FPACK_WINDOWS_SIGN_DLIB_METADATA windows.sign.dlib_metadata path dlib 的元数据文件(/dmdf),如 Trusted Signing 的账户和证书配置。
FPACK_SNAP_BUILD_MODE linux.snap.build_mode auto \ destructive \

按用途分类的变量#

变量作用
FPACK_FLUTTERFlutter SDK 路径
FPACK_CONFIG配置文件路径
FPACK_MODE FPACK_FLAVOR FPACK_ENTRY FPACK_BUILD_NAME FPACK_BUILD_NUMBER 构建参数
FPACK_OUTPUT_DIR FPACK_OVERWRITE FPACK_SPLIT_PER_ABI FPACK_OBFUSCATE 输出 / Android / 混淆
FPACK_ANDROID_KEYSTORE FPACK_ANDROID_KEYSTORE_BASE64 FPACK_ANDROID_KEYSTORE_PASSWORD FPACK_ANDROID_KEY_ALIAS FPACK_ANDROID_KEY_PASSWORD Android 签名
FPACK_IOS_EXPORT_METHOD FPACK_IOS_EXPORT_OPTIONS_PLIST FPACK_IOS_CODESIGN iOS 导出
FPACK_MACOS_SIGN FPACK_MACOS_SIGN_IDENTITY FPACK_MACOS_INSTALLER_IDENTITY FPACK_MACOS_NOTARIZE FPACK_MACOS_NOTARY_PROFILE FPACK_NOTARIZE_WAIT FPACK_MACOS_PROVISIONING_PROFILE FPACK_MACOS_PROFILE_CHECK FPACK_MACOS_SMOKE_TEST FPACK_DMG_TOOL macOS
FPACK_NOTARY_APPLE_ID FPACK_NOTARY_TEAM_ID FPACK_NOTARY_PASSWORD FPACK_NOTARY_API_KEY FPACK_NOTARY_API_KEY_ID FPACK_NOTARY_API_ISSUER macOS 公证凭证(Apple ID / API 密钥)
FPACK_WINDOWS_CERTIFICATE FPACK_WINDOWS_CERTIFICATE_PASSWORD FPACK_WINDOWS_CERT_THUMBPRINT FPACK_WINDOWS_CERT_SUBJECT FPACK_WINDOWS_SIGN_DLIB FPACK_WINDOWS_SIGN_DLIB_METADATA Windows 代码签名(.pfx、证书存储,或 Azure Trusted Signing 等 signtool dlib)
FPACK_LANGzh / en(默认跟随系统语言,见下文「输出语言」)
NO_COLOR / FPACK_NO_COLOR / FORCE_COLOR颜色控制
FPACK_CORE指定原生核心二进制(开发用)
FPACK_HOME核心缓存目录
FPACK_REBUILD=1强制先用本机 Go 重新编译核心(修改了 Go 源码时)
FPACK_GO回退编译时使用的 Go(none 表示禁止本机编译)
FPACK_NO_DOWNLOAD=1 / FPACK_DOWNLOAD_URL 禁止下载(直接本机编译) / 自定义下载地址(内网镜像);见启动器如何找到原生核心

输出语言#

fpack(Go 核心和 Dart 启动器)在操作系统语言为中文(任何 zh 变体:简体、繁体、香港等)时使用中文,其余情况一律使用英文。所有内容都随之切换:提示信息、帮助、doctor / list 输出、错误提示、fpack init 生成的 fpack.yaml 注释,以及 NOTARIZATION.md。

优先级(先匹配者生效):

  1. --lang zh|en
  2. FPACK_LANG=zh|en
  3. 操作系统语言:
    • macOS:系统设置 → 通用 → 语言与地区 中的第一个语言(defaults read -g AppleLanguages),其次 AppleLocale。终端通常按“地区”设置 LANG(即使界面是中文也常为 en_US.UTF-8),所以只有读取失败时才使用 LANG / LANGUAGE;显式设置的 LC_ALL 或 LC_MESSAGES 仍然优先。结果缓存在 ~/Library/Caches/fpack/os-language,系统偏好设置变化后自动刷新。
    • Windows:用户的显示语言(GetUserDefaultUILanguage,不启动子进程);忽略 Git Bash/MSYS 设置的 LANG,显式的 LC_ALL / LC_MESSAGES 仍然优先。
    • Linux 等:依次读取 LC_ALL、LC_MESSAGES、LANGUAGE(第一项)、LANG;跳过 C / POSIX。

fpack 读取的其他变量#

变量用途
FLUTTER_ROOT、FVM_CACHE_PATH 查找 Flutter SDK(在 --flutter 、 FPACK_FLUTTER 、 flutter.sdk 与项目的 FVM 链接之后)
ANDROID_HOME / ANDROID_SDK_ROOT Android SDK 工具( apksigner ),顺序与 Flutter 相同:先 flutter config --android-sdk ,再这两个变量,最后默认安装目录
JAVA_HOME keytool / Java 版本检查:先 flutter config --jdk-dir 与 Android Studio 自带的 JDK,再 JAVA_HOME ,最后 PATH
XDG_CONFIG_HOME、APPDATA 读取 Flutter 设置文件的位置(--android-sdk / --jdk-dir)
LOCALAPPDATA、ProgramFiles、ProgramFiles(x86) Windows:Android SDK、Inno Setup、FVM 与 Flutter 的默认安装位置
LC_ALL、LC_MESSAGES、LANGUAGE、LANG 输出语言(见上文)
NO_COLOR、FPACK_NO_COLOR、TERM=dumb、FORCE_COLOR 颜色;TERM=dumb 同时关闭进度动画
COLUMNS无法获取终端宽度时的表格宽度
XDG_CACHE_HOME启动器:Linux 上的缓存根目录(可被 FPACK_HOME 覆盖)

fpack 为钩子设置的变量#

fpack 把这些变量传给钩子;它们是输出,不是设置。

变量值
FPACK_PROJECT_ROOT项目目录
FPACK_OUTPUT_DIR产物目录
FPACK_VERSION、FPACK_BUILD_NUMBER版本名和构建号
FPACK_MODE、FPACK_FLAVOR构建模式和 flavor
FPACK_TARGET目标(pre_package / post_package)
FPACK_ARTIFACT、FPACK_ARTIFACTS 产物(post_package、post_build)
FPACK_SUCCESS1 或 0(post_build)