使用 Flutter 构建 Windows 应用

本页讨论使用 Flutter 构建 Windows 应用时的特有注意事项，包括 shell 集成以及通过 Windows 上的 Microsoft Store 分发应用。

Windows 编程接口结合了传统 Win32 API、COM 接口以及更现代的 Windows Runtime 库。由于它们均提供基于 C 的 ABI，你可以使用 Dart 的外部函数接口库（dart:ffi）调用操作系统提供的服务。FFI 旨在使 Dart 程序高效调用 C 库，为 Flutter 应用提供使用 malloc 或 calloc 分配原生内存、支持指针/结构体/回调，以及 long、size_t 等 ABI 类型的能力。

有关从 Flutter 调用 C 库的更多信息，请参阅使用 dart:ffi 的 C 互操作。

实践中，虽然以这种方式从 Dart 调用基本 Win32 API 相对直接，但使用封装 COM 编程模型复杂细节的包装库会更简单。win32 package 提供可访问数千种常用 Windows API 的库，并使用 Microsoft 提供的元数据以确保一致性与正确性。该包还包含多种常见用例示例，例如 WMI、磁盘管理、shell 集成和系统对话框。

许多其他包在此基础上构建，为 Windows registry、gamepad support、biometric storage、taskbar integration、serial port access 等提供符合 Dart 习惯的访问方式。

更一般地，还有许多其他支持 Windows 的包，包括 url_launcher、shared_preferences、file_selector 和 path_provider 等常用包。

你可以使用包括 Material 在内的任意视觉风格或主题；部分应用作者可能希望构建符合 Microsoft Fluent design system 惯例的应用。fluent_ui 包（Flutter Favorite）为现代 Windows 应用中常见的视觉与控件提供支持，包括导航视图、内容对话框、浮出层、日期选择器和树形视图 widget。

此外，Microsoft 提供 fluentui_system_icons，可方便地在 Flutter 应用中使用数千个 Fluent 图标。

最后，bitsdojo_window 包支持“自绘”标题栏，允许你用与应用其余部分匹配的自定义标题栏替换标准 Windows 标题栏。

创建 Windows 应用时，Flutter 会生成承载 Flutter 的小型 C++ 应用。该“runner 应用”负责创建并调整传统 Win32 窗口大小、初始化 Flutter 引擎与任何原生插件，以及运行 Windows 消息循环（将相关消息传递给 Flutter 进一步处理）。

当然，你可以根据需要修改此代码，包括更改应用名称与图标，以及设置窗口的初始大小与位置。相关代码在 main.cpp 中，类似如下：

Win32Window::Point origin(10, 10);
Win32Window::Size size(1280, 720);
if (!window.CreateAndShow(L"myapp", origin, size))
{
    return EXIT_FAILURE;
}

将 myapp 替换为你希望在 Windows 标题栏中显示的标题，并可选择调整 size 的尺寸与窗口坐标。

要更改 Windows 应用图标，请将 windows\runner\resources 目录中的 app_icon.ico 替换为你偏好的图标。

可通过编辑 windows/CMakeLists.txt 中的 BINARY_NAME 变量更改生成的 Windows 可执行文件名：

cmake_minimum_required(VERSION 3.14)
project(windows_desktop_app LANGUAGES CXX)

# The name of the executable created for the application.
# Change this to change the on-disk name of your application.
set(BINARY_NAME "YourNewApp")

cmake_policy(SET CMP0063 NEW)

运行 flutter build windows 时，build\windows\runner\Release 目录中生成的可执行文件将使用新名称。

最后，应用可执行文件的更多属性位于 windows\runner 目录的 Runner.rc 文件中。你可以在此更改嵌入 Windows 应用、并在 Windows 资源管理器属性对话框中显示的版权信息与应用版本。要更改版本号，请编辑 VERSION_AS_NUMBER 与 VERSION_AS_STRING 属性；其他信息可在 StringFileInfo 块中编辑。

对大多数应用，使用 flutter run 与 flutter build 让 Flutter 处理编译即可。若你对 runner 应用做了重大修改或将 Flutter 集成到现有应用中，可能希望在 Visual Studio 中直接加载或编译 Flutter 应用。

请按以下步骤操作：

1. 运行 flutter build windows 以创建 build\ 目录。

2. 打开 Windows runner 的 Visual Studio 解决方案文件；它现在位于 build\windows 目录中，名称与父 Flutter 应用一致。

3. 在解决方案资源管理器中你会看到多个项目。右键单击与 Flutter 应用同名的项目，选择 Set as Startup Project（设为启动项目）。

4. 要生成必要依赖，请运行 Build > Build Solution（生成 > 生成解决方案）

   你也可以按 Ctrl + Shift + B。

   要从 Visual Studio 运行 Windows 应用，请转到 Debug > Start Debugging（调试 > 开始调试）。

   你也可以按 F5。

5. 使用工具栏在 Debug 与 Release 配置之间切换。

分发 Windows 应用有多种方式，例如：

• 使用工具为你的应用构建 MSIX 安装程序（见下一节），并通过 Microsoft Windows 应用商店分发。此方式无需手动创建签名证书，由平台代为处理。

• 构建 MSIX 安装程序并通过你自己的网站分发。此方式需要以 .pfx 证书形式为应用提供数字签名。

• 收集所有必要文件并自行打包 zip。

MSIX 是新的 Windows 应用包格式，提供现代打包格式与安装程序。该格式可用于将应用发布到 Windows 上的 Microsoft Store，也可直接分发安装程序。

为 Flutter 项目创建 MSIX 分发包的最简单方式是使用 msix pub package。有关在 Flutter 桌面应用中使用 msix 包的示例，请参阅 Desktop Photo Search 示例。

借助 MSIX 安装程序进行私有部署与测试时，你需要以 .pfx 证书形式为应用提供数字签名。

通过 Windows Store 部署时无需生成 .pfx 证书；商店会处理通过其商店分发的应用的证书创建与管理。

若通过自建网站分发应用，则需要由 Windows 认可的证书颁发机构签名的证书。

使用以下说明生成自签名 .pfx 证书。

1. 若尚未下载，请下载 OpenSSL 工具包以生成证书。

2. 进入 OpenSSL 安装目录，例如 C:\Program Files\OpenSSL-Win64\bin。

3. 设置环境变量以便从任意位置访问 OpenSSL：
   "C:\Program Files\OpenSSL-Win64\bin"

4. 按如下方式生成私钥：
   openssl genrsa -out mykeyname.key 2048

5. 使用私钥生成证书签名请求（CSR）文件：
   openssl req -new -key mykeyname.key -out mycsrname.csr

6. 使用私钥与 CSR 文件生成已签名证书（CRT）文件：
   openssl x509 -in mycsrname.csr -out mycrtname.crt -req -signkey mykeyname.key -days 10000

7. 使用私钥与 CRT 文件生成 .pfx 文件：
   openssl pkcs12 -export -out CERTIFICATE.pfx -inkey mykeyname.key -in mycrtname.crt

8. 在安装应用前，请先将 .pfx 证书安装到本地计算机的 Certificate store（证书存储），作为 Trusted Root Certification Authorities（受信任的根证书颁发机构）。

Flutter 可执行文件 .exe 位于项目的 build\windows\runner\<build mode>\ 下。除该可执行文件外，你还需要：

• From the same directory:

  • all the .dll files
  • the data directory

  同一目录中：

  • 所有 .dll 文件
  • data 目录

• The Visual C++ redistributables. You can use any of the methods shown in the deployment example walkthroughs on the Microsoft site to ensure that end users have the C++ redistributables. If you use the application-local option, you need to copy:

  • msvcp140.dll
  • vcruntime140.dll
  • vcruntime140_1.dll

  Visual C++ 可再发行组件。可使用 Microsoft 站点上的部署示例演练中的任一方法，确保最终用户拥有 C++ 可再发行组件。若使用 application-local 选项，需要复制：

  • msvcp140.dll
  • vcruntime140.dll
  • vcruntime140_1.dll

  将 DLL 放在可执行文件与其他 DLL 旁的目录中，并一起打包为 zip。结果结构类似：

  Release
  │   flutter_windows.dll
  │   msvcp140.dll
  │   my_app.exe
  │   vcruntime140.dll
  │   vcruntime140_1.dll
  │
  └───data
  │   │   app.so
  │   │   icudtl.dat
  
  ...
  

  content_copy

此时若需要，可较容易地将该文件夹加入 Inno Setup、WiX 等 Windows 安装程序。

要了解如何使用 Inno Setup 构建 .exe 以分发 Windows 版 Flutter 桌面应用，请参阅分步 Windows packaging guide。