dart-compilation-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dart-compilation

Goal

目标

Compiles Dart source code into optimized, target-specific formats including self-contained native executables, ahead-of-time (AOT) snapshots, just-in-time (JIT) modules, and web-deployable JavaScript or WebAssembly. Assumes the Dart SDK is installed, the target environment is configured, and the source code does not rely on unsupported libraries (e.g.,

dart:mirrors

) for native compilation.

将Dart源代码编译为针对特定目标的优化格式，包括独立原生可执行文件、提前编译（AOT）快照、即时编译（JIT）模块、可部署到Web的JavaScript或WebAssembly。本指南默认你已安装Dart SDK、完成目标环境配置，且源代码不依赖原生编译不支持的库（例如

dart:mirrors

）。

Decision Logic

决策逻辑

Use the following logic to determine the appropriate compilation target:

Is the target a Web environment?
- Yes -> Use
```
dart compile js
```
  (or
```
dart compile wasm
```
  ). See Related Skill:
  dart-web-development
  .
Is the target a Native OS (Windows, macOS, Linux)?
- Does the deployment require a single, self-contained binary?
  - Yes -> Use
```
dart compile exe
```
    .
- Is the deployment environment resource-constrained (e.g., embedded systems, containers) where multiple apps share a runtime?
  - Yes -> Use
```
dart compile aot-snapshot
```
    and execute with
```
dartaotruntime
```
    .
- Does the application benefit from profile-guided optimization via a training run?
  - Yes -> Use
```
dart compile jit-snapshot
```
    .
Is the target platform-agnostic?
- Yes -> Use
```
dart compile kernel
```
  to generate a portable
```
.dill
```
  file.

使用以下逻辑确定合适的编译目标：

目标是否为Web环境？
- 是 -> 使用
```
dart compile js
```
  （或
```
dart compile wasm
```
  ）。相关技能：
  dart-web-development
  。
目标是否为原生操作系统（Windows、macOS、Linux）？
- 部署是否需要单个独立的二进制文件？
  - 是 -> 使用
```
dart compile exe
```
    。
- 部署环境是否为资源受限环境（例如嵌入式系统、容器），且多个应用共享运行时？
  - 是 -> 使用
```
dart compile aot-snapshot
```
    ，并通过
```
dartaotruntime
```
    执行。
- 应用是否能通过训练运行实现配置引导优化？
  - 是 -> 使用
```
dart compile jit-snapshot
```
    。
目标是否需要跨平台兼容？
- 是 -> 使用
```
dart compile kernel
```
  生成可移植的
```
.dill
```
  文件。

Instructions

使用指南

Determine Compilation Target and Parameters Evaluate the project requirements against the Decision Logic. STOP AND ASK THE USER: "Which target platform and architecture are you compiling for? Do you require cross-compilation (e.g., compiling for Linux ARM64 from macOS)?"
Compile to Self-Contained Executable (Native) For standard native binaries, use the
```
exe
```
subcommand. This bundles the machine code and a minimal Dart runtime.
bash
```
dart compile exe bin/main.dart -o build/app.exe
```
Cross-Compilation (Linux targets only):
bash
```
dart compile exe \
  --target-os=linux \
  --target-arch=arm64 \
  bin/main.dart -o build/app_linux_arm64
```
Compile to AOT Snapshot (Resource-Constrained) For environments where disk space is limited and a shared runtime is preferred, generate an AOT snapshot.
bash
```
dart compile aot-snapshot bin/main.dart -o build/app.aot
```
Execution:
bash
```
dartaotruntime build/app.aot
```

Compile to Web Targets (JS / Wasm) For web deployments, compile to optimized JavaScript or WebAssembly.

bash

# Compile to JS with aggressive optimizations (O2 is safe, O3/O4 omit type checks)
dart compile js -O2 -o build/app.js web/main.dart

# Compile to WebAssembly
dart compile wasm web/main.dart -o build/app.wasm

Compile to JIT or Kernel Modules (Specialized) JIT Snapshot (requires a training run):

bash

dart compile jit-snapshot bin/main.dart -o build/app.jit
dart run build/app.jit

Portable Kernel:

bash

dart compile kernel bin/main.dart -o build/app.dill
dart run build/app.dill

Validate-and-Fix Loop After executing the compilation command, verify the output file exists and test its execution.
bash
```
# Verify file generation
ls -la build/

# Test execution (example for exe)
./build/app.exe
```
Error Handling: If compilation fails due to build hooks, fallback to
```
dart build
```
. If type errors occur in JS compilation at
```
-O3
```
or
```
-O4
```
, downgrade to
```
-O2
```
and recompile.

确定编译目标和参数 结合决策逻辑评估项目需求。 请停止并询问用户： "你编译的目标平台和架构是什么？是否需要交叉编译（例如从macOS编译Linux ARM64版本）？"
编译为独立可执行文件（原生） 对于标准原生二进制文件，请使用
```
exe
```
子命令。该命令会打包机器码和最小化的Dart runtime。
bash
```
dart compile exe bin/main.dart -o build/app.exe
```
交叉编译（仅支持Linux目标）：
bash
```
dart compile exe \
  --target-os=linux \
  --target-arch=arm64 \
  bin/main.dart -o build/app_linux_arm64
```
编译为AOT快照（资源受限场景） 对于磁盘空间有限、优先使用共享运行时的环境，请生成AOT快照。
bash
```
dart compile aot-snapshot bin/main.dart -o build/app.aot
```
执行方式：
bash
```
dartaotruntime build/app.aot
```

编译为Web目标（JS / Wasm） 对于Web部署场景，编译为优化后的JavaScript或WebAssembly。

bash

# 编译为高优化等级JS（O2为安全等级，O3/O4会省略类型检查）
dart compile js -O2 -o build/app.js web/main.dart

# 编译为WebAssembly
dart compile wasm web/main.dart -o build/app.wasm

编译为JIT或Kernel模块（特殊场景） JIT快照（需要训练运行）：

bash

dart compile jit-snapshot bin/main.dart -o build/app.jit
dart run build/app.jit

可移植Kernel：

bash

dart compile kernel bin/main.dart -o build/app.dill
dart run build/app.dill

验证与修复循环 执行编译命令后，验证输出文件是否存在并测试其可执行性。
bash
```
# 验证文件生成
ls -la build/

# 测试执行（以exe为例）
./build/app.exe
```
错误处理： 如果编译因构建钩子失败，请回退到
```
dart build
```
。如果在
```
-O3
```
或
```
-O4
```
级别编译JS时出现类型错误，请降级到
```
-O2
```
后重新编译。

Constraints

约束条件

DO NOT use
```
dart compile exe
```
or
```
dart compile aot-snapshot
```
if the package or its dependencies utilize build hooks; these commands will fail. Use
```
dart build
```
instead.
DO NOT use
```
dart:mirrors
```
or
```
dart:developer
```
in code targeted for
```
exe
```
or
```
aot-snapshot
```
compilation.
DO use
```
dart compile exe
```
for self-contained native binaries on Windows/macOS/Linux.
DO use
```
dart compile js
```
or
```
dart compile wasm
```
for web deployment targets.
DO optimize for performance using AOT compilation where supported.
DO use
```
dartaotruntime
```
for running AOT snapshots in resource-constrained environments.
DO NOT attempt cross-compilation for target operating systems other than Linux.
DO NOT use
```
-O3
```
or
```
-O4
```
JavaScript optimizations without verifying that the application never throws a subtype of
```
Error
```
(e.g.,
```
TypeError
```
) and handles edge-case user input safely.

如果包或其依赖使用了构建钩子，禁止使用
```
dart compile exe
```
或
```
dart compile aot-snapshot
```
，这些命令会执行失败，请改用
```
dart build
```
。
针对
```
exe
```
或
```
aot-snapshot
```
编译的代码中，禁止使用
```
dart:mirrors
```
或
```
dart:developer
```
。
针对Windows/macOS/Linux平台的独立原生二进制文件，请使用
```
dart compile exe
```
。
针对Web部署目标，请使用
```
dart compile js
```
或
```
dart compile wasm
```
。
在支持的场景下，请使用AOT编译优化性能。
在资源受限环境中运行AOT快照时，请使用
```
dartaotruntime
```
。
禁止尝试针对Linux以外的操作系统进行交叉编译。
未验证应用不会抛出
```
Error
```
子类（例如
```
TypeError
```
）、且能安全处理边缘用户输入的情况下，禁止使用
```
-O3
```
或
```
-O4
```
等级的JavaScript优化。