## 插件系统 插件可用于自定义和优化 Nuitka 编译的行为，根据项目的需求选择适当的插件以获得最佳性能和功能。在某些情况下，如果未显式地启用插件可能会导致预期之外地错误。 ## 插件控制 * `--enable-plugin=PLUGIN_NAME`: 启用插件。必须是插件名称。使用`--plugin-list`查询完整列表并退出。默认为空。 * `--disable-plugin=PLUGIN_NAME`: 禁用插件。必须是插件名称。使用`--plugin-list`查询完整列表并退出。大多数标准插件禁用后可能不是一个好主意。默认为空。 * `--plugin-no-detection`: 插件可以检测是否可能会被使用，然后您可以通过`--disable-plugin=plugin-that-warned`禁用警告，或者您可以使用此选项完全禁用机制，这也会稍微加快编译速度，因为这个检测代码在您确定要使用哪些插件后就是徒劳的。默认关闭。 * `--plugin-list`: 显示所有可用插件的列表并退出。默认关闭。 * `--user-plugin=PATH`: 用户插件的文件名。可以多次提供。默认为空。 * `--show-source-changes`: 显示编译前原始Python文件内容的源更改。主要用于开发插件。默认为False。 #### `anti-bloat`插件的选项 * `--show-anti-bloat-changes`: 注释插件所做的更改。 * `--noinclude-setuptools-mode=NOINCLUDE_SETUPTOOLS_MODE`: 当遇到`setuptools`或相关导入时的处理方式。这个包可能包含大量依赖项，应该绝对避免。还处理`setuptools_scm`导入。 * `--noinclude-pytest-mode=NOINCLUDE_PYTEST_MODE`: 当遇到`pytest`导入时的处理方式。这个包可能包含大量依赖项，应该绝对避免。还处理`nose`导入。 * `--noinclude-unittest-mode=NOINCLUDE_UNITTEST_MODE`: 当遇到`unittest`导入时的处理方式。这个包可能包含大量依赖项，应该绝对避免。 * `--noinclude-IPython-mode=NOINCLUDE_IPYTHON_MODE`: 当遇到`IPython`导入时的处理方式。这个包可能包含大量依赖项，应该绝对避免。 * `--noinclude-dask-mode=NOINCLUDE_DASK_MODE`: 当遇到`dask`导入时的处理方式。这个包可能包含大量依赖项，应该绝对避免。 * `--noinclude-numba-mode=NOINCLUDE_NUMBA_MODE`: 当遇到`numba`导入时的处理方式。这个包包含大量依赖项，目前不适用于独立模式。应该绝对避免。 * `--noinclude-default-mode=NOINCLUDE_DEFAULT_MODE`: 实际上提供了上述选项的默认 “warning” 值，可用于将所有这些选项都打开。 * `--noinclude-custom-mode=CUSTOM_CHOICES`: 当遇到特定导入时的处理方式。格式为模块名称，这应该是一个顶级包，然后是一个选项，例如“error”，“warning”，“nofollow”，例如`PyQt5:error`。 ## 支持的插件 * **anti-bloat** * 修补不必要的导入，来自库模块源代码。 * **data-files** * 包括包配置文件指定的数据文件。 * **delvewheel** * 支持使用delvewheel包的"support"，适用于独立模式。 * **dill-compat** * 用于与"dill"包兼容性的支持。 * **dll-files** * 包括DLL，根据包配置文件。 * **enum-compat** * 支持Python 2 和"enum"包。 * **eventlet** * 支持"eventlet"依赖项和对"dns"包的猴子补丁。 * **gevent** * 为'gevent'包提供支持。 * **gi** * 支持GI包typelib依赖。 * **glfw** * OpenGL和'glfw'包的支持，适用于独立模式。 * **implicit-imports** * 根据包配置文件提供包的隐式导入。 * **kivy** * 为'kivy'包提供支持。 * **matplotlib** * 支持'matplotlib'模块。 * **multiprocessing** * 支持Python的'multiprocessing'模块。 * **no-qt** * 禁用所有Qt绑定，适用于独立模式。 * **options-nanny** * 根据包配置文件通知用户潜在问题。 * **pbr-compat** * 为'pbr'包在独立模式下提供兼容性支持。 * **pkg-resources** * 解决'pkg\_resources'的问题。 * **pmw-freezer** * 为'Pmw'包提供支持。 * **pylint-warnings** * 支持PyLint / PyDev的linting源标记。 * **pyqt5** * 为PyQt5包提供支持。 * **pyqt6** * 为PyQt6包在独立模式下提供支持。 * **pyside2** * 为PySide2包提供支持。 * **pyside6** * 为PySide6包在独立模式下提供支持。 * **pywebview** * 为'webview'包 (PyPI上的pywebview) 提供支持。 * **tk-inter** * 支持Python的Tk模块。 * **transformers** * 为transformers包提供隐式导入。 * **upx** * 自动使用UPX压缩创建的二进制文件。 . ## Nuitka 的跨平台支持 `Nuitka`是跨平台支持的，对 Windows macOS 和 Linux 均有良好的支持，除了提供通用的操作系统支持之外，还针对三个操作系统做了特定控制的支持。下面将一一介绍。 ## 通用操作系统控制 * `--disable-console`在为 Windows 或 macOS 编译时，禁用控制台窗口并创建 GUI 应用程序。默认关闭。 * `--enable-console`在为 Windows 或 macOS 编译时，启用控制台窗口并创建控制台应用程序。这会禁用某些模块的提示，例如`PySide`，建议禁用控制台。默认为`true`。 * `--force-stdout-spec=FORCE_STDOUT_SPEC`强制将程序的标准输出发送到此位置。对于禁用控制台的程序和使用 Nuitka 商业版的 Windows Services 插件的程序非常有用。默认不激活，例如使用`%PROGRAM_BASE%.out.txt`，即在程序附近的文件。 * `--force-stderr-spec=FORCE_STDERR_SPEC`强制将程序的标准错误发送到此位置。对于禁用控制台的程序和使用 Nuitka 商业版的 Windows Services 插件的程序非常有用。默认不激活，例如使用`%PROGRAM_BASE%.err.txt`，即在程序附近的文件。 ## Windows 特定控制 * `--windows-icon-from-ico=ICON_PATH`添加可执行文件图标。可以多次提供不同分辨率或具有多个图标的文件。在后一种情况下，还可以附加`#<n>`，其中n是从1开始的整数索引，指定要包括的特定图标，所有其他图标都将被忽略。 * `--windows-icon-from-exe=ICON_EXE_PATH`从现有可执行文件中复制可执行文件图标（仅适用于Windows）。 * `--onefile-windows-splash-screen-image=SPLASH_SCREEN_IMAGE`在为Windows和onefile编译时，在加载应用程序时显示此图像。默认关闭。 * `--windows-uac-admin`请求Windows用户控制，以在执行时授予管理员权限（仅适用于Windows）。默认关闭。 * `--windows-uac-uiaccess`请求Windows用户控制，以强制仅从少数文件夹运行（仅适用于Windows远程桌面访问）。默认关闭。 ## macOS 特定控制 * `--macos-target-arch=MACOS_TARGET_ARCH`指定该程序应该在哪些体系结构上运行。默认限制为当前运行Python允许的体系结构。默认为"native"，即与运行Python的体系结构相同。 * `--macos-create-app-bundle`在为 macOS 编译时，创建一个应用程序包而不是一个普通的二进制应用程序。目前是实验性和不完整的。目前这是解锁禁用控制台的唯一方法。默认关闭。 * `--macos-app-icon=ICON_PATH`为应用程序包添加图标以使用。只能提供一次。如果可用，将使用Python图标。默认情况下。 * `--macos-signed-app-name=MACOS_SIGNED_APP_NAME`用于 macOS 签名的应用程序的名称。最好按照`com.YourCompany.AppName`的命名结果进行命名，因为这些名称必须是全局唯一的，并且可能授予受保护的 API 访问权限。 * `--macos-app-name=MACOS_APP_NAME`在 macOS 包信息中使用的产品名称。默认为二进制文件的基本文件名。 * `--macos-app-mode=MODE`应用程序包的应用程序模式。当需要启动窗口并显示在 Docker 中时，默认值`gui`是一个很好的选择。如果根本没有窗口，该应用程序是一个 background 应用程序。对于稍后要显示的UI元素，ui-element 处于中间状态。该应用程序将不会出现在 dock 中，但在稍后打开窗口时将获得对桌面的完全访问。 * `--macos-sign-identity=MACOS_APP_VERSION`在 macOS 上签名时，默认情况下将使用临时标识符，但使用此选项，您可以指定另一个要使用的标识符。现在在 macOS 上强制签名代码，无法禁用。默认为`ad-hoc`（即临时标识符）。 * `--macos-sign-notarization`在签名时进行标记，使用 Apple 的正确 TeamID 标识符，使用所需的运行时签名选项以便可以接受。 * `--macos-app-version=MACOS_APP_VERSION`在 macOS 包信息中使用的产品版本。默认为`1.0`，如果未提供。 * `--macos-app-protected-resource=RESOURCE_DESC`请求访问 macOS 受保护资源的授权。例如，`NSMicrophoneUsageDescription:Microphone access for recording audio.`请求访问麦克风并为用户提供有关为何需要该权限的信息。在冒号之前是一个 OS 标识符，用于访问权限的识别，然后是信息性文本。可以多次指定。默认为空。 ## Linux 特定控制 * `--linux-icon=ICON_PATH`为 onefile 二进制文件添加可执行文件图标。只能提供一次。如果可用，将使用 Python 图标。 . ## 什么是版本元数据 版本元数据就是用来描述二进制文件的信息，版本等数据的，例如下面在 Windows 上的属性截图，在不同的操作系统上都可以提供对可执行文件的元数据支持。  在 Nuitka 中，允许你进行二进制版本信息控制。 ## 二进制版本信息 * `--company-name=COMPANY_NAME`在版本信息中使用的公司名称。默认未使用。 * `--product-name=PRODUCT_NAME`在版本信息中使用的产品名称。默认为二进制文件的基本文件名。 * `--file-version=FILE_VERSION`在版本信息中使用的文件版本。必须是最多4个数字的序列，例如1.0或1.0.0.0，不允许更多的数字，也不允许字符串。默认未使用。 * `--product-version=PRODUCT_VERSION`在版本信息中使用的产品版本。与文件版本的规则相同。默认未使用。 * `--file-description=FILE_DESCRIPTION`在版本信息中使用的文件描述（目前仅在 Windows 上可用）。默认情况下为二进制文件名。 * `--copyright=COPYRIGHT_TEXT`在版本信息中使用的版权信息（目前仅适用于 Windows）。默认未使用。 * `--trademarks=TRADEMARK_TEXT`在版本信息中使用的商标信息（目前仅适用于 Windows）。默认未使用。 . ## 进阶编译控制 从这里开始，我们可以更加精细的控制 Nuitka 的编译控制，包括控制 C 编译器，启用链接优化，控制缓存，启用 C 级别的分析优化，注意，这些控制涉及到 C 级别的控制，如果你不知道自己做什么，那么请不要尝试，可能导致无法预知的行为。 ## C 编译器控制 * `--clang`强制使用 clang 编译器。在 Windows 上，这需要一个可用的 Visual Studio版本来支持。默认关闭。 * `--mingw64`强制在 Windows 上使用 MinGW64。默认关闭，除非使用 MSYS2 与 MinGW Python。 * `--msvc=MSVC_VERSION`强制在 Windows 上使用特定的 MSVC 版本。允许的值例如`"14.3"（MSVC 2022）`和其他 MSVC 版本号，指定`"list"`以获取已安装的编译器列表，或使用`"latest"`。默认为安装的最新 MSVC 版本，否则使用 MinGW64。 * `--jobs=N`指定允许的并行 C 编译器作业数量。默认为系统CPU数量。如果编译期间负载过大，可能手动指定，但是我一般在编译的时候去摸鱼。 * `--lto=choice`使用链接时间优化（MSVC、gcc、clang）。允许的值为`"yes"`、`"no"`和`"auto"`（已知可用时）。默认为`"auto"`。 * `--static-libpython=choice`使用 Python 的静态链接库。允许的值为`"yes"`、`"no"`和`"auto"`（已知可用时）。默认为`"auto"`。 ## 缓存控制 * `--disable-cache=DISABLED_CACHES`禁用选定的缓存，指定`"all"`以禁用所有缓存。目前允许的值包括：`"all"`、`"ccache"`、`"bytecode"`、`"dll-dependencies"`。可以多次指定或以逗号分隔的方式提供。默认为无。 * `--clean-cache=CLEAN_CACHES`在执行之前清除给定的缓存，指定`"all"`以清除所有缓存。目前允许的值包括：`"all"`、`"ccache"`、`"bytecode"`、`"dll-dependencies"`。可以多次指定或以逗号分隔的方式提供。默认为无。 * `--disable-bytecode-cache`不重用模块的依赖分析结果，特别是来自标准库的模块，它们被包含为字节码。等同于`--disable-cache=bytecode`。 * `--disable-ccache`不尝试使用 ccache（gcc、clang等）或 clcache（MSVC、clangcl）。等同于`--disable-cache=ccache`。 * `--disable-dll-dependency-cache`禁用依赖关系分析器缓存。这将导致创建分发文件夹的时间大大增加，但如果怀疑缓存可能导致错误，则可能会使用它。等同于`--disable-cache=dll-dependencies`。 * `--force-dll-dependency-cache-update`用于更新依赖关系分析器缓存。这将导致创建分发文件夹的时间大大增加，但如果怀疑缓存可能导致错误或已知需要更新，则可能会使用它。 ## PGO 编译控制 * `--pgo`启用 C 级别的分析优化（PGO），通过首先执行专用的构建以进行分析运行，然后将结果反馈到 C 编译中。注意：这是实验性的，尚不适用于 Nuitka 的独立模式。默认关闭。 * `--pgo-args=PGO_ARGS`在进行分析优化时要传递的参数。这些参数传递给在 PGO 分析运行期间使用的特殊构建可执行文件。默认为空。 * `--pgo-executable=PGO_EXECUTABLE`在收集配置文件信息时要执行的命令。仅在需要通过准备运行它的脚本来启动它时使用。默认使用创建的程序。 . ## 强大的调试与追踪控制 其实在 Nuitka 中，自带了许多强大的调试和追踪报告功能，能够允许你对程序运行的诸多细节进行追踪和调试，这对于部署真正的生产级别的代码是至关重要地。但是在中文互联网甚至是英文我鲜少有看到实际介绍这部分的文章，这未免有些浪费，下面我将介绍如何使用 Nuitka 内置的调试与追踪功能来生成详细的报告。 ## 调试 * `--debug`执行尽可能多的自检以查找Nuitka中的错误。不要用于生产。默认关闭。 * `--unstripped`在生成的对象文件中保留调试信息，以实现更好的调试器交互。默认关闭。 * `--profile`启用基于vmprof的时间分析。目前不工作。默认关闭。 * `--internal-graph`创建优化过程内部的图形，不要用于整个程序，仅用于小型测试案例。默认关闭。 * `--trace-execution`追踪执行输出，在执行代码之前输出代码行。默认关闭。 * `--recompile-c-only`这不是增量编译，而仅用于 Nuitka 开发。它采用现有文件，仅将其重新编译为 C。允许编译已编辑的 C 文件，以快速调试生成的源代码更改，例如查看代码是否被通过，输出值等。默认关闭。取决于编译 Python 源代码来确定应查看哪些文件。 * `--xml=XML_FILENAME`将优化过程的内部程序结构以 XML 形式写入给定的文件名。 * `--generate-c-only`仅生成 C 源代码，不编译为二进制或模块。这用于不浪费 CPU 的调试和代码覆盖分析。默认关闭。不要认为你可以直接使用它。 * `--experimental=FLAG`使用声明为`“experimental”`的功能。如果代码中没有实验性功能，则可能不起作用。使用实验性标签（检查源代码）进行每个实验的功能。 * `--low-memory`尝试使用更少的内存，通过减少 C 编译作业的分支和使用使用更少内存的选项。用于嵌入式设备。如果遇到内存不足问题，请使用此选项。默认关闭。但是根据我的经验来看，大部分告警内存不足基本都是由于你的编译姿势不对所导致的，请优先排除其他错误，最后考虑此选项。 * `--create-environment-from-report=CREATE_ENVIRONMENT_FROM_REPORT`从给定的报告文件创建新的虚拟环境，例如`'--report=compilation-report.xml'`。默认不执行。 ## 报告与追踪 * `--report=REPORT_FILENAME`以 XML 输出文件的形式报告模块、数据文件、编译、插件等详细信息。这对于问题报告也非常有用。这些报告可以用于通过`'--create-environment-from-report'`轻松重新创建环境，但包含大量信息。默认关闭。 * `--report-diffable`以可比较的形式报告数据，即没有时间或内存使用值的变化。默认关闭。 * `--report-user-provided=KEY_VALUE`报告来自您的数据。可以多次提供，格式为`'key=value'`，其中`key`应为标识符，例如，使用`'--report-user-provided=pipenv-lock-hash=64a5e4'`来跟踪某些输入值。默认为空。 * `--report-template=REPORT_DESC`通过模板进行报告。提供模板和输出文件名`"template.rst.j2:output.rst"`。对于内置模板，请查看用户手册以了解这些模板是什么。可以多次提供。默认为空。 * `--quiet`禁用所有信息输出，但显示警告。默认关闭。 * `--show-scons`以详细信息运行 C 构建后端 Scons，显示执行的命令和检测到的编译器。默认关闭。 * `--no-progressbar`禁用进度条。默认关闭。 * `--show-progress`提供进度信息和统计信息。禁用正常的进度条。默认关闭。现在已经停止支持。 * `--show-memory`提供内存信息和统计信息。默认关闭。 * `--show-modules`提供包含的模块和 DLL 的信息。已过时，你应该使用`'--report'`文件代替。默认关闭。 * `--show-modules-output=PATH`指定`'--show-modules'`的输出位置，应为文件名。默认为标准输出。 * `--verbose`输出所采取的行动的详细信息，特别是在优化中。可能会变得非常多。默认关闭。 * `--verbose-output=PATH`指定`'--verbose'`。 . ## 编译选项和完成时行为控制 在编译完成后，我们可以立刻启动或者直接进入调试，在编译过程中我们也可以严格规定兼容 CPython，以及控制产物的输出等等。 ## 编译完成时行为 * `--run`立即执行创建的二进制文件（或导入已编译的模块）。默认关闭。 * `--debugger`在调试器中执行，例如`gdb`或`lldb`，以自动获取堆栈跟踪。默认关闭。 * `--execute-with-pythonpath`在使用`--run`立即执行创建的二进制文件或模块时，不重置`PYTHONPATH`环境变量。当所有模块都成功包含时，不再需要`PYTHONPATH`，特别是在独立模式下。这非常适合调试不同版本。 ## 编译选择 * `--user-package-configuration-file=YAML_FILENAME`用户提供的包配置的 YAML 文件。可以包括 DLL，删除庞杂内容，添加隐藏的依赖项。查看用户手册以获取要使用的格式的完整描述。可以多次提供。默认为空。 * `--full-compat`强制与 CPython 的绝对兼容性。甚至不允许对 CPython 行为的微小偏差，例如没有更好的回溯或不真正不兼容但只是不同或更差的异常消息。**这仅用于测试，不应使用**。 * `--file-reference-choice=MODE`选择`__file__`的值。使用`runtime`（独立二进制模式和模块模式的默认值）时，创建的二进制文件和模块使用它们自身的位置来推断`__file__`的值。包含的包会伪装成在该位置下的目录中。这允许在部署中包含数据文件。如果您只是寻求加速，最好使用`original`值，其中源文件位置将被使用。使用`frozen`时，使用`<frozen module_name>`的表示法。出于兼容性原因，`__file__`值始终将具有 ".py" 后缀，不管它实际上是什么。这里其实我也没有搞球太懂。 * `--module-name-choice=MODE`选择`__name__`和`__package__`的值。使用`runtime`（模块模式的默认值）时，创建的模块使用父包来推断`__package__`的值，以实现完全兼容。使用`original`（其他模式的默认值）允许进行更多的静态优化，但对于通常可以加载到任何包中的模块来说是不兼容的。也是没搞懂。 ## 输出选项 * `--output-filename=FILENAME`指定可执行文件的命名方式。对于扩展模块，没有选择，也不适用于独立模式，使用它将会报错。但是，它可能包含需要存在的路径信息。默认为平台上的 '' + '.exe'。 * `--output-dir=DIRECTORY`指定中间和最终输出文件的位置。DIRECTORY将填充具有构建文件夹、分发文件夹、二进制文件等的文件夹。默认为当前目录。 * `--remove-output`在生成模块或二进制产物后删除构建目录。默认关闭。 * `--no-pyi-file`不为由 Nuitka 创建的扩展模块创建 ".pyi" 文件。这用于检测隐式导入。默认关闭。