命令列選項

設定 Native Image 的選項分為以下類別

建置選項：執行 native-image --help 以取得建置選項的說明。
額外建置選項：執行 native-image --help-extra 以取得額外建置選項的說明。
專家建置選項：執行 native-image --expert-options 以取得專家選項的說明。

根據 GraalVM 版本，native-image 建置器的選項可能有所不同。

Native Image 選項也可以分類為託管選項或執行階段選項。

託管選項：用於設定建置程序，例如，影響原生二進位檔中包含的內容以及建置方式。這些選項使用前綴 -H:。
執行階段選項：在建置原生二進位檔時提供初始值，使用前綴 -R:。在執行階段，預設前綴為 -XX:（這是應用程式特定的，並非 Native Image 所強制規定）。

如需更多關於如何定義和使用這些選項的資訊，請參閱 com.oracle.svm.core.option 套件文件。

建置選項 #

執行 native-image --help 以取得建置選項的說明。

-cp, -classpath, --class-path <類別搜尋路徑，包含目錄和 ZIP/JAR 檔案>：一個以 : (Windows 上為 ;) 分隔的目錄、JAR 封存和 ZIP 封存清單，用於搜尋類別檔案
-p <模組路徑>, --module-path <模組路徑>：一個以 : (Windows 上為 ;) 分隔的目錄清單。每個目錄都是一個模組的目錄。
--add-modules <模組名稱>[,<模組名稱>...]：除了初始模組之外，新增要解析的根模組。 <模組名稱> 也可以是 ALL-DEFAULT、ALL-SYSTEM、ALL-MODULE-PATH。
-D<名稱>=<值>：設定系統屬性
-J<旗標>：直接將選項傳遞至執行 native-image 建置器的 JVM
--diagnostics-mode：啟用診斷輸出：類別初始化、取代等。
--enable-preview：允許類別依賴此版本的預覽功能
--enable-native-access <模組名稱>[,<模組名稱>...]：啟用允許執行受限原生作業的模組。 <模組名稱> 也可以是 ALL-UNNAMED
--verbose：啟用詳細輸出
--version：列印產品版本並結束
--help：列印此說明訊息
--help-extra：列印非標準選項的說明
--auto-fallback：盡可能建置獨立可執行檔
--color：為建置輸出著色 (always、never 或 auto)
--configure-reflection-metadata：啟用對未調用方法的反射物件執行階段實例化
--emit：在建置結果中發出額外資料。使用 build-report 發出詳細的建置報告，例如：--emit build-report 或 --emit build-report=report.html
--enable-all-security-services：將所有安全性服務類別新增至產生的原生可執行檔
--enable-http：在原生可執行檔中啟用 HTTP 支援
--enable-https：在原生可執行檔中啟用 HTTPS 支援
--enable-monitoring：啟用允許在執行階段檢查 VM 的監控功能。逗號分隔清單可以包含 heapdump、jfr、jvmstat、jmxserver（實驗性）、jmxclient（實驗性）、threaddump 或 all (已淘汰行為：如果未提供任何引數，則預設為 all)。例如：--enable-monitoring=heapdump,jfr。
--enable-sbom：在可執行檔或共用程式庫中嵌入軟體物料清單 (SBOM)，以供被動檢查。逗號分隔清單可以包含 cyclonedx、strict（如果未提供任何引數，則預設為 cyclonedx）或 export 以將 SBOM 儲存至原生可執行檔的輸出目錄。如果任何類別無法與 SBOM 中的程式庫相符，則選用的 strict 旗標會中止建置。例如：--enable-sbom=cyclonedx,strict。（在 GraalVM 社群版中無法使用。）
--enable-url-protocols：列出要啟用的逗號分隔 URL 通訊協定
--features：以逗號分隔的完整限定 Feature 實作類別清單
--force-fallback：強制建置回退原生可執行檔
--gc=<值>：選取 Native Image 垃圾收集器實作。 <值> 允許的選項為：G1 代表 G1 垃圾收集器 (在 GraalVM 社群版中無法使用)；epsilon 代表 Epsilon 垃圾收集器；serial 代表循序垃圾收集器（預設）。
--initialize-at-build-time：以逗號分隔的套件和類別清單 (及其所有隱含的父類別)，在產生原生可執行檔期間會進行初始化。空字串表示所有套件。
--initialize-at-run-time：以逗號分隔的套件和類別清單 (及其所有隱含的子類別)，必須在執行階段初始化，而不是在產生期間初始化。目前不支援空字串。
--install-exit-handlers：提供 java.lang.Terminator 結束處理常式
--libc：選取要使用的 libc 實作。可用的實作為 glibc、musl、bionic。
--link-at-build-time：要求在原生可執行檔建置時完全定義類型。如果未使用任何引數，則選項範圍中的所有類別都必須完全定義。
--link-at-build-time-paths：要求在原生可執行檔建置時完全定義指定類別或模組路徑項目中的所有類型
--list-cpu-features：顯示特定於目標平台的 CPU 功能並結束
--list-modules：列出可觀察的模組並結束
--native-compiler-options：提供用於查詢程式碼編譯的自訂 C 編譯器選項
--native-compiler-path：提供用於查詢程式碼編譯和連結的自訂 C 編譯器路徑
--native-image-info：顯示原生工具鏈資訊和可執行檔的建置設定
--no-fallback：建置獨立原生可執行檔或回報失敗
--parallelism：指定在產生原生可執行檔期間同時使用的最大執行緒數
--pgo：提供一個以逗號分隔的檔案清單，用於讀取為 AOT 編譯程式碼的設定檔引導最佳化所收集的資料（如果未指定任何內容，則從 default.iprof 讀取）。每個檔案都必須包含一個 PGOProfiles 物件，以 JSON 格式序列化，可以選擇使用 gzip 壓縮。（在 GraalVM 社群版中無法使用。）
--pgo-instrument：檢測 AOT 編譯的程式碼，以將設定檔引導最佳化的資料收集到 default.iprof 檔案中。（在 GraalVM 社群版中無法使用。）
--pgo-sampling：藉由取樣 AOT 編譯的程式碼執行設定檔，以收集設定檔引導最佳化的資料。（在 GraalVM 社群版中無法使用。）
--shared：建置共用程式庫
--silent：隱藏建置輸出
--static：建置靜態連結的可執行檔（需要 libc 和 zlib 靜態程式庫）
--static-nolibc：建置靜態連結的可執行檔，但動態連結 libc
--target：選取 native-image 的編譯目標（格式為 <作業系統>-<架構>）。預設為主機的作業系統架構配對。
--trace-class-initialization：提供一個以逗號分隔的完整限定類別名稱清單，追蹤類別的初始化
--trace-object-instantiation：提供一個以逗號分隔的完整限定類別名稱清單，追蹤物件的實例化
-O<層級>：控制程式碼最佳化，其中可用的變體為：b - 針對最快的建置時間進行最佳化、s - 針對大小進行最佳化、0 - 不進行最佳化、1 - 基本最佳化、2 - 積極最佳化、3 - 針對最佳效能進行所有最佳化 (透過設定檔引導最佳化自動啟用)
-da、-da[:[套件名稱]|:[類別名稱]、disableassertions[:[套件名稱]|:[類別名稱]：在執行階段停用具有指定精細度的判斷提示
-dsa、-disablesystemassertions：在執行階段停用所有系統類別中的判斷提示
-ea、-ea[:[套件名稱]|:[類別名稱]、enableassertions[:[套件名稱]|:[類別名稱]：在執行階段啟用具有指定精細度的判斷提示
-esa、-enablesystemassertions：在執行階段啟用所有系統類別中的判斷提示
-g：產生偵錯資訊
-march：為特定機器類型產生指令。在 AMD64 上預設為 x86-64-v3，在 AArch64 上預設為 armv8-a。如果原生可執行檔部署在同一部機器上或具有相同 CPU 功能的機器上，請使用 -march=compatibility 以獲得最佳相容性，或使用 -march=native 以獲得最佳效能。若要列出所有可用的機器類型，請使用 -march=list。
-o：要產生的輸出檔案名稱

額外建置選項 #

執行 native-image --help-extra 以取得額外選項的說明。

--exclude-config：排除逗號分隔的類別路徑/模組路徑模式和資源模式的設定。例如：--exclude-config foo.jar,META-INF\/native-image\/.*.properties 會忽略名為 foo.jar 的所有 JAR 檔案中的 META-INF/native-image 中的所有屬性檔案。
--expert-options：列出專家映像建置選項
--expert-options-all：列出所有專家的映像建置選項 (自行承擔風險)。標示為提供額外說明的選項包含可以使用 --expert-options-detail 顯示的說明
--expert-options-detail：顯示以逗號分隔的選項名稱清單的所有可用說明。傳遞 * 以顯示包含它的所有選項的額外說明。
--configurations-path <選項設定目錄的搜尋路徑>：要視為選項設定目錄的分隔目錄清單。
--debug-attach[=<連接埠或主機:連接埠 (* 可以用作主機，表示繫結至所有介面)>]：在產生原生可執行檔期間連接至偵錯工具 (預設連接埠為 8000)
--diagnostics-mode：啟用將映像建置資訊記錄至診斷目錄。
--dry-run：輸出將用於建置的命令列
--bundle-create[=new-bundle.nib]：除了映像建置之外，還會建立一個原生映像套件檔案 (*.nibfile)，允許稍後再次重建該映像。如果傳遞套件檔案，則會使用指定的名稱建立套件。否則，套件檔案名稱會從映像名稱衍生。請注意，這兩個套件選項都可以使用 dry-run 和 container 擴充。
- dry-run：只執行套件作業，而不會建置任何實際的原生可執行檔
- container：設定容器映像檔，並在該容器內執行原生可執行檔的產生。需要安裝 Podman 或無根 Docker。如果兩者都可用，Podman 為首選，無根 Docker 作為備用。指定其中一個為 =<container-tool> 會強制使用特定的工具。
- dockerfile=<Dockerfile>：使用使用者提供的 Dockerfile，而不是基於適用於 GraalVM 的 Oracle Linux 8 基礎映像檔的預設 Dockerfile。
--bundle-apply=some-bundle.nib[,dry-run][,container[=<container-tool>][,dockerfile=<Dockerfile>]]：將會使用傳遞給 Native Image 以建立套件的完全相同引數和檔案，從指定的套件檔案建立映像檔。請注意，如果在 --bundle-apply 之後傳遞額外的 --bundle-create，則會根據指定的套件引數以及之後傳遞的任何其他引數來寫入新的套件。例如：native-image --bundle-apply=app.nib --bundle-create=app_dbg.nib -g 會根據指定的 app.nib 套件建立新的 app_dbg.nib 套件。兩個套件都相同，只是新的套件也使用了 -g 選項。
-E<env-var-key>[=<env-var-value>]：允許 Native Image 在產生原生可執行檔期間存取指定的環境變數。如果未提供可選的 <env-var-value>，則環境變數的值將取自呼叫 Native Image 時的環境。
-V<key>=<value>：為 native-image.properties 檔案中的佔位符提供值。
--add-exports：值 <module>/<package>=<target-module>(,<target-module>) 會更新 <module> 以將 <package> 匯出至 <target-module>，無論模組宣告為何。<target-module> 可以是 ALL-UNNAMED 以匯出至所有未命名的模組。
--add-opens：值 <module>/<package>=<target-module>(,<target-module>) 會更新 <module> 以將 <package> 開啟至 <target-module>，無論模組宣告為何。
--add-reads：值 <module>=<target-module>(,<target-module>) 會更新 <module> 以讀取 <target-module>，無論模組宣告為何。<target-module> 可以是 ALL-UNNAMED 以讀取所有未命名的模組。

有用的選項清單 #

有一些專家級的選項，使用者可能會覺得有用或需要。例如，傾印 native-image 建構器的圖形，或在建置過程中列印各種統計資訊的選項。

建置輸出和建置報告 #

Native Image 提供資訊豐富的建置輸出，包括建置過程中的各種統計資訊。可以使用 -H:BuildOutputJSONFile 選項請求 JSON 格式的機器可讀建置輸出，然後由監控工具處理。JSON 檔案會根據 build-output-schema-v0.9.3.json 中定義的 JSON 結構描述進行驗證。可以使用 --emit build-report 選項請求包含其他資訊的完整報告。

注意：--emit build-report 選項在 GraalVM 社群版中不可用。

圖形傾印 #

Native Image 重複使用了來自 GraalVM 除錯環境的圖形傾印、記錄、計數器和所有其他選項。這些 GraalVM 選項既可以用作**託管選項**（如果您想傾印 native-image 建構器的圖形），也可以用作**執行階段**選項（如果您想在執行階段的動態編譯期間傾印圖形）。

按預期工作的 Graal 編譯器選項包括 Dump、DumpOnError、Log、MethodFilter，以及為傾印處理程式指定檔案名稱和連接埠的選項。例如

-H:Dump= -H:MethodFilter=ClassName.MethodName：傾印 native-image 建構器的編譯器圖形。
-XX:Dump= -XX:MethodFilter=ClassName.MethodName：在執行階段傾印編譯圖形。