This article walks through the journey from discovering the problem, to attempts at fixing it, to researching solutions, and finally to the implementation — hoping to provide some reference for developers facing similar issues.

I’d also love for you to try out and discuss the Flutter Package I wrapped: native_natural_sort.

1. The Problem

1.1. First Version: Default compareTo Sorting

mhabit supports several sorting modes, of which “sort by name” is one of the most commonly used. The first version was dead simple — it used Dart’s built-in String.compareTo:

data.sort((a, b) => a.name.compareTo(b.name));

compareTo is essentially lexicographic ordering — it compares characters one by one by their Unicode code points. For purely ASCII English it seems to work fine, but once mixed case, non-Latin characters, and numbers enter the picture, problems start to appear.

1.2. First Pitfall: Case Sensitivity

The first issue noticed was case sensitivity. compareTo sorts by code points, and uppercase A (U+0041) has a smaller code point than lowercase a (U+0061), so all names starting with uppercase letters sort before lowercase ones:

An intuitive fix is to normalize to lowercase:

data.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));

That solved the case issue. But more problems soon surfaced.

1.3. Second Pitfall: CJK, Diacritics, and Numbers

toLowerCase() fixed case, but never touched the root cause — Unicode code point order ≠ the order humans expect:

The number issue: the first character "1" of "10" has a smaller code point than "2", so "10" sorts before "2". The diacritic issue: á (U+00E1) has a code point far greater than z (U+007A), so árbol ends up at the end. The Chinese issue is more complex — compareTo sorts by Unicode code point, and within the CJK Unified Ideographs block, the order of 张 (U+5F20), 李 (U+674E), 王 (U+738B) has nothing to do with pinyin lǐ, wáng, zhāng.

At this point it became clear: simple case normalization is far from enough — you need a sort that understands language rules.

2. Choosing a Solution

Armed with the problems above, I started systematically researching viable solutions. In the end I narrowed it down to five directions (plus one seemingly promising but ultimately impractical middle path, discussed separately after Solution A):

2.1. Solution Overview

2.2. Solution A: Hand-written Pure Dart Natural Sort

The most naive idea — implement it yourself. Split the string into text chunks and number chunks with a regex, compare text chunks with compareTo, and compare number chunks numerically.

Pros: zero dependencies, fully controllable.

Cons:

• Only solves numeric sorting; cannot handle locale-aware comparison (CJK, diacritics)
• Implementing the full Unicode Collation Algorithm (UCA)^[1] is a huge undertaking — UCA is a complete Unicode Technical Standard (UTS #10) that ICU has spent decades polishing
• Sorting rules differ greatly between languages (German ß=ss, Swedish å after z, Chinese by pinyin/strokes), and you’d have to maintain a rule set for every language you add

Conclusion: workable for simple cases, but impractical for a multi-language app like this.

2.3. A Seemingly Great Middle Path: Transliterate to Pinyin Then Sort

During research, one idea was seriously considered: transliterate non-Latin scripts to Latin letters first, then sort. For example, Chinese to pinyin (张→zhang), Japanese to romanization (東京→toukyou), Arabic to Latin transliteration (سلام→salaam), then sort the transliterated text with compareTo.

The appeal: pure Dart, zero platform dependencies, simple logic. pub.dev also has ready-made pinyin packages (e.g., pinyin, lpinyin), so it looked like a simple char→pinyin→compareTo three-step solution.

But on closer analysis, this path has a few inescapable pitfalls.

2.3.1. Arabic: Transliteration Loses the Sorting Tradition

Arabic letters have their own independent sorting traditions. According to Wikipedia^[2], there are two main Arabic orders: the traditional Abjadi order and the hijāʾī order used by modern dictionaries — both completely different from the Latin a b c d... sequence. Transliterating Arabic letters into Latin (ا→a, ب→b) and sorting by the Latin order yields results that don’t match what Arabic speakers recognize as correct.

In other words, transliteration-based sorting for Arabic isn’t just “imprecise” — it fundamentally applies the wrong rules.

2.3.2. Chinese: The Maintenance Nightmare of Hardcoded Dictionaries

The core problem with Chinese-to-pinyin isn’t the transliteration logic itself, but the data it depends on.

Existing pinyin packages (pinyin, lpinyin, etc.) work by hardcoding the character→pinyin mapping from Unicode/Unihan into Dart source files. pinyin was last released 2 years ago, with dictionary data from Unihan 15.0.0; lpinyin hasn’t been updated for 5 years. Unihan gets a new release every year — new characters, fixed readings, additional context for polyphonic characters — but these dictionaries are frozen in time. New Unicode characters entered by users may fail to transliterate, and officially corrected readings never get synced.

2.3.3. Summary

Transliterate-then-sort looks like a shortcut, but because the process discards the original language’s sorting semantics, it produces wrong results for writing systems with independent sorting traditions (such as Arabic’s Abjadi/hijāʾī order). Combined with the poor maintenance status of pinyin packages on pub.dev, this path is a dead end.

2.4. Solution B: collection.compareNatural

Dart’s official collection package provides a compareNatural function specifically for natural sorting. It’s also listed among the implementations in the Wikipedia “Natural sort order” article^[3].

Pros: maintained by the Dart team, zero additional dependencies (collection is already a transitive dependency of Flutter), and numeric sorting is correct.

Cons: compareNatural only solves numeric sorting; it does not support locale awareness. Chinese still sorts by Unicode code point, and diacritics are still unhandled. Essentially it’s just “a better Solution A”.

Conclusion: a reasonable fallback, but not the final answer.

2.5. Solution C: Bundling Traditional ICU Data

ICU (International Components for Unicode) is the Unicode Consortium’s official i18n library, with a complete collation implementation. Some Dart packages link ICU via FFI and bundle collation data into the app.

Pros: complete functionality, correct sorting results.

Cons:

• ICU collation data is roughly 10~30MB — a significant size cost for mobile apps
• Requires compiling native libraries, complicating cross-platform builds
• The collation data version is fixed and won’t improve automatically as the OS updates

Conclusion: powerful but too heavy — better suited for scenarios needing full control over ICU.

2.6. Solution D: icu4x + intl4x

ICU4X is the Unicode Consortium’s next-generation i18n library rewritten in Rust for resource-constrained environments, designed around “small and modular code” and “pluggable locale data”. On the Dart side, the official intl4x package provides an FFI wrapper that already supports collation.

This is the closest thing to an “official solution” and deserves careful analysis.

See intl4x/lib/collation.dart:

final list = ['Z', 'a', 'z', 'ä'];
final german = Collation(locale: Locale.parse('de-DE'));
list.sort(german.compare);
print(list); // [a, ä, z, Z]

Pros:

• Maintained by the Dart team (labs.dart.dev), with long-term support assurance
• Complete functionality: collation + datetime + number + plural + display names
• Built on ICU4X, architecturally more modular than traditional ICU
• Cross-platform support

Cons:

• Significantly larger binary size: the README explicitly states “This package currently increases binary size in non-web builds significantly”, mitigable only with the experimental --enable-experiment=record-use flag
• Flathub builds need extra preprocessing: intl4x depends on the icu4x FFI native library, which requires compiling Rust ICU4X → .so/.dylib/.dll. The Flathub build sandbox is fully offline and cannot run cargo build to download dependencies — exactly the pitfall encountered in the previous Flathub post. There are two workarounds: pre-compile each platform’s binary and commit it into the source tree (as recommended by the official flow), or manually add a Rust vendoring + offline compilation module to the flatpak-builder manifest. Either way, Flatpak packaging maintenance complexity increases significantly.
• Experimental stage: the current stable version is 0.17.0, the API is still iterating, and the icu4x Dart binding is only at 0.0.1 stable — it actually depends on a pre-release (2.2.0-dev.3)
• Heavy dependency: just for collation, you’d pull in the entire i18n framework (datetime, number, plural, case mapping, etc.) — clear over-engineering for a use case that only needs string sorting

Conclusion: most powerful and officially endorsed, but too heavy, costly to maintain for Flathub packaging, and — as of 2026-08 — not yet in a stable release, so using it carries significant risk.

2.7. Solution E: Calling the Platform-Native Sorting Engine

Every operating system already ships a mature sorting engine — Android has android.icu.text.Collator, iOS/macOS have localizedStandardCompare:, Linux has libicui18n, Windows has CompareStringEx, and the Web has Intl.Collator^[4].

These APIs have been silently working in the background — Finder sorts files by name, Android file managers sort files, Windows Explorer sorts files — all thanks to them. So why not call them directly?

This solution takes a hybrid route: desktop platforms prefer FFI (synchronous) to call system libraries directly, while mobile platforms bridge native APIs via Platform Methods (asynchronous), uniformly exposing a Future interface. Linux goes through FFI→libicui18n, Windows uses FFI→ICU DLL primarily with Pigeon→CompareStringEx as a fallback, and Android/iOS/macOS — whose docs don’t expose FFI-friendly public collation entry points — use platform bridging for maintainability reasons.

Pros:

• Zero additional size: no collation data bundled; calls the OS built-in API directly
• System consistency: sorting results match the system file manager exactly
• Automatic updates: collation data improves as the OS updates, no package version bump needed
• Flathub-friendly: no extra downloads/compilation; pure Dart + Pigeon/FFI calls to system APIs
• All platforms: every major Flutter platform has a mature system-level collation API

Cons:

• Requires writing different bridging code per platform (FFI / Platform Method)
• Some platforms require async calls: Android/iOS/macOS go through platform channels (async), meaning you can’t directly pass the comparator to List.sort(). That said, Linux (FFI→ICU) and Windows (FFI→ICU DLL) are synchronous under the hood — for API consistency, the package uniformly returns Future, and callers handle it asynchronously
• Platform API behaviors may differ subtly
• Unified error handling and graceful fallback are needed on the Dart side

Conclusion: lightweight, Flathub-compatible, and small in size — a great balance for apps that don’t need absolute control over multi-platform consistency but want quick access to natural-language sorting or the closest possible consistency with the system experience.

3. Implementation

3.1. Phase One: Platform Wrappers Inside mhabit

Once Solution E was chosen, the first thing wasn’t to create a standalone package immediately — it was to get each platform’s sorting call working inside the app first, validating the feasibility of the approach.

The core idea:

• Define a unified sorting interface on the Dart side (SortItem + NativeSort.sort())
• Desktop calls system collation libraries directly via Dart FFI
  • Linux→libicui18n
  • Windows→ICU DLL, also providing a Pigeon fallback (CompareStringEx)
• Mobile bridges native APIs via Pigeon (Android/iOS/macOS)

NativeSort (Dart API)
├── Android   → Pigeon → android.icu.text.Collator
├── iOS       → Pigeon → localizedStandardCompare:
├── macOS     → Pigeon → localizedStandardCompare:
├── Linux     → Dart FFI → system libicui18n
├── Windows   → Pigeon (CompareStringEx) or FFI (ICU)
└── Web       → Dart → Intl.Collator

3.2. Phase Two: Extracting a Standalone Package

After getting it working inside the project, I found three reasons this code deserved to be published as a package:

1. pub.dev has no similar all-platform native sorting solution. collection.compareNatural only solves numeric sorting, and intl4x is too heavy and experimental — in the “lightweight, all-platform, native sorting” niche, there’s a clear gap.

2. Flathub compatibility is a hard requirement. mhabit is already published on Flathub, and any dependency requiring extra downloads/compilation is unacceptable. intl4x/icu4x exactly fit that description — they need extra FFI compilation, requiring patches or pre-compilation, which is annoying and fragile. We’ve already been burned by this with the sqlite3 package.

3. Decoupling and reuse. Sorting logic is business-agnostic; extracted, it can be tested independently, released independently, and referenced by other Flutter projects.

And so native_natural_sort came to be.

3.3. Integrating into mhabit

The mhabit integration changes are concentrated in a few files.

See lib/main.dart:

await NativeSort().config(
  SortOptions(
    windows: SortOptionsWindows.ffi(onLoadFailed: WindowsSort.pigeon),
  ),
);

A one-time initialization in main(). On Windows, it configures a dual-backend fallback of FFI (ICU) → Pigeon (CompareStringEx).

See lib/extensions/collation_extensions.dart, which wraps a generic naturalSort<T> extension method that accepts idOf/valueOf functions to adapt to arbitrary data types:

extension NaturalSortExtension on NativeSort {
  Future<List<T>> naturalSort<T>({
    required List<T> items,
    required String Function(T) idOf,
    required String Function(T) valueOf,
    bool descending = false,
    String? locale,
  }) async {
    if (items.isEmpty) return items;
    final sortItems = items
        .map((e) => SortItem(id: idOf(e), value: valueOf(e)))
        .toList();
    final sorted = await sort(sortItems, /* ... */);
    // Map sorted IDs back to original items.
    // ...
  }
}

At the ViewModel layer, the sorting logic goes through a SortGuard with graceful fallback:

• When natural sort is enabled and the sort mode is “by name”, take the async native sorting path
• If the async sort fails (e.g., a platform API exception), automatically fall back to the default compareTo sort so functionality never crashes
• SortGuard ensures that only the latest result survives concurrent re-sort requests

See _ResortHandler in lib/pages/habits_display/_providers/habit_summary.dart:

class _ResortHandler {
  FutureOr<_HabitsSortableCache> call() {
    final needHabitNatural =
        cache.sortType == HabitDisplaySortType.name &&
        _vm._naturalSortEnabled;
    final needGroupNatural = /* ... */;

    if (!needHabitNatural && !needGroupNatural) return defaultSort();
    return _guardedNaturalSort(needHabitNatural, needGroupNatural);
  }
}

It also exposes a NaturalSortExperimentalFeature toggle so users can choose whether to enable native sorting (on by default).

3.4. Async Refactor: The SortGuard Pattern

The hybrid route of Solution E brings a practical engineering problem: FFI sorting on Linux/Windows is synchronous under the hood, but Pigeon sorting on Android/iOS/macOS is asynchronous. For API consistency, native_natural_sort uniformly returns Future. This means the original synchronous sorting logic — which all Solutions A~D could do with a direct list.sort(compareFn) — needed an async refactor.

mhabit’s approach is to introduce SortGuard — a simple counter-based sort guard. The core idea:

• Call _sortGuard.bump() before each data reload, incrementing the generation
• Wrap the sort with _sortGuard.run(), capturing the current generation
• After the async sort completes, compare generations — if they differ, the data has changed and the result is invalid

See lib/common/sort_generation.dart:

class SortGuard {
  int _generation = 0;

  void bump() { _generation++; }

  FutureOr<T?> run<T>(FutureOr<T> Function() sort) {
    final token = _generation;
    final result = sort();
    return result is Future<T>
        ? result.then((r) => _generation == token ? r : null)
        : (_generation == token ? result : null);
  }
}

In the ViewModel, _resortData()’s return type changed from void to FutureOr<void> — the synchronous path (default sort) returns directly, the async path (native sort) returns a Future, and callers handle both uniformly with await _resortData(), keeping the interface unchanged.

Combined with a .catchError((e) => defaultSort()) graceful fallback, the async refactor is completely transparent to upper layers.

3.5. The Final Result

After integrating native_natural_sort, the “sort by name” results compared:

All the problems mentioned earlier are now well resolved.

4. Summary

Looking back, the core lesson is: string sorting looks simple, but once you have multi-language users, don’t reinvent the wheel.

The Unicode Collation Algorithm (UCA) is a standard that has evolved over decades, and every OS already ships a battle-tested implementation. Instead of bundling ICU data or relying on experimental frameworks, calling the OS-native API directly is the more pragmatic choice — zero size growth (no ICU database to maintain), system-level correctness, and automatic improvement as the OS updates.

The package is now published on pub.dev/native_natural_sort. If you’re building a multi-language Flutter app and hitting similar issues, I hope this package helps.

References

1. Unicode Collation Algorithm (UCA) — Wikipedia
2. Abjad numerals — Wikipedia
3. Natural sort order — Wikipedia
4. Intl.Collator — MDN Web Docs

本文将从问题的发现开始，依次介绍修复尝试、方案调研以及最终的实现方案，希望能为遇到类似问题的开发者提供一些参考。

同时，也欢迎体验和交流我封装的 Flutter Package: native_natural_sort。

1. 问题

1.1. 第一版：compareTo 默认排序

mhabit 支持多种排序方式，其中「按名称排序」是最常用的之一。 第一版实现非常简单，就是 Dart 内置的 String.compareTo：

data.sort((a, b) => a.name.compareTo(b.name));

compareTo 本质上是字典序——按 Unicode 码点逐字符比较。对于纯 ASCII 英文来说似乎工作正常， 但一旦涉及混合大小写、非英文字符、数字，问题就来了。

1.2. 第一个坑：大小写

最早被注意到的是大小写问题。compareTo 按码点排序，大写字母 A（U+0041）的码点小于小写 a（U+0061）， 导致所有大写开头的名称排在小写前面：

一个直观的修复是统一转为小写：

data.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));

大小写问题解决了。但很快更多的问题出现了。

1.3. 第二个坑：CJK、变音符号、数字

toLowerCase() 修好了大小写，但根本没有触及排序的根本问题——Unicode 码点顺序 ≠ 人类期望的排序顺序：

数字的问题在于 "10" 的第一个字符 "1" 码点小于 "2"，所以 "10" 排在 "2" 前面。 变音符号 á（U+00E1）的码点远大于 z（U+007A），所以 árbol 被排到了末尾。 中文的问题更复杂——compareTo 按 Unicode 码点排序，对于 CJK 统一表意文字区块， 张（U+5F20）、李（U+674E）、王（U+738B）的顺序与拼音 lǐ, wáng, zhāng 完全不同。

至此，必须承认：简单的大小写归一化远远不够，需要一种理解语言规则的排序方式。

2. 方案选择

带着上面的问题，我开始系统性地调研可行的解决方案。最终梳理出五种方向（外加一种看似美好但实际不太可行的折中方案， 在方案 A 之后单独讨论）：

2.1. 方案概览

2.2. 方案 A：手写纯 Dart 自然排序

最朴素的想法——自己实现。按正则将字符串拆分为文本块和数字块， 文本块用 compareTo 比较，数字块按数值比较。

优点：零依赖，完全可控。

缺点：

• 只能解决数字排序，无法处理 locale 感知的比较（CJK、变音符号）
• 要实现完整的 Unicode Collation Algorithm (UCA)^[1] 工作量巨大——UCA 是一个完整的 Unicode 技术标准（UTS #10），ICU 用了数十年才打磨成熟
• 不同语言的排序规则差异很大（德语 ß=ss、瑞典语 å 在 z 之后、中文按拼音/笔画），每加一种语言就要维护一份规则

结论：对简单场景可行，但对这种多语言应用不实际。

2.3. 一个看似美好的折中路线：转拼音再排序

在调研过程中，有一个思路曾经认真考虑过：先把非拉丁文字转写为拉丁字母，再排序。 比如中文转拼音（张→zhang）、日文转罗马字（東京→toukyou）、 阿拉伯文转拉丁转写（سلام→salaam），转写后用 compareTo 排序。

这个方案的诱惑力在于：纯 Dart 实现、零平台依赖、逻辑简单。 pub.dev 上也有现成的拼音转换包（如 pinyin、lpinyin）， 看起来只要 char→pinyin→compareTo 三步就能解决问题。

但仔细分析后，这条路有几个绕不开的坑。

2.3.1. 阿拉伯文：转写 = 丢失排序传统

阿拉伯字母有自己独立的排序传统。根据 Wikipedia^[2]， 阿拉伯文存在两种主要排序：传统的 Abjadi 序和现代词典使用的 hijāʾī 序， 两者都与拉丁字母 a b c d... 的排列完全不同。将阿拉伯字母转写为拉丁字母 （如 ا→a、ب→b）后按拉丁序排列，得到的结果与阿拉伯语使用者认知中的 正确顺序不相符。

换句话说，转写排序对阿拉伯文不只是「不精确」，而是从根本上用错了排序规则。

2.3.2. 中文：硬编码字典的维护困境

中文转拼音的核心问题不在转写逻辑本身，而在于依赖的数据。

现有拼音包（pinyin、lpinyin 等）的工作方式是 把 Unicode/Unihan 的字符→拼音映射表硬编码到 Dart 源文件中。 pinyin 最新版发布于 2 年前，字典数据来自 Unihan 15.0.0； lpinyin 更是5 年未曾更新。Unihan 每年都有新版本——新增字符、 修正读音、补充多音字语境——但字典就此冻结。用户输入的新 Unicode 汉字可能转拼音失败， 官方修正的读音错误也不会被同步。

2.3.3. 小结

转拼音再排序看上去是一条捷径，但因为转写过程丢弃了原始语言的排序语义， 对于有独立排序传统的书写系统（如阿拉伯文的 Abjadi/hijāʾī 序）会得到错误结果。 加上 pub.dev 上拼音包的维护现状堪忧，这条路走不通。

2.4. 方案 B：collection.compareNatural

Dart 官方的 collection 包提供了 compareNatural 函数， 专门用于自然排序。从 Wikipedia Natural Sort Order^[3] 列出的各语言实现中也能看到它。

优点：Dart 官方维护，零额外依赖（collection 已是 Flutter 的传递依赖），数字排序正确。

缺点：compareNatural 只解决数字排序，不支持 locale 感知。 它对中文仍然按 Unicode 码点排序，对变音符号也无力处理。本质上只是「更好的方案 A」。

结论：可以作为 fallback，但不能作为最终方案。

2.5. 方案 C：打包传统 ICU 数据

ICU（International Components for Unicode）是 Unicode 官方的 i18n 库， 包含完整的 collation 实现。部分 Dart 包通过 FFI 链接 ICU，将 collation 数据打包进 App。

优点：功能完整，排序结果正确。

缺点：

• ICU collation 数据约 10~30MB，对移动端应用是显著的体积代价
• 需要编译原生库，跨平台构建复杂
• collation 数据版本固定，不会随 OS 更新自动改善

结论：功能强但太重，更适合需要完全掌控 ICU 的场景。

2.6. 方案 D：icu4x + intl4x

ICU4X 是 Unicode 官方用 Rust 重写的、面向资源受限环境的新一代 i18n 库， 设计目标包含「small and modular code」「pluggable locale data」。 Dart 侧由官方 intl4x 包提供 FFI 封装，已支持 collation。

这是最接近「官方方案」的选择，需要重点分析。

参考 intl4x/lib/collation.dart:

final list = ['Z', 'a', 'z', 'ä'];
final german = Collation(locale: Locale.parse('de-DE'));
list.sort(german.compare);
print(list); // [a, ä, z, Z]

优点：

• Dart 官方维护（labs.dart.dev），长期支持有保障
• 功能完整：collation + datetime + number + plural + display names
• 基于 ICU4X，设计上比传统 ICU 更模块化
• 全平台支持

缺点：

• 二进制体积显著增加：README 明确声明「This package currently increases binary size in non-web builds significantly」，需使用 --enable-experiment=record-use 实验性标志缓解
• Flathub 构建需额外预处理：intl4x 依赖 icu4x FFI 原生库，后者需要编译 Rust ICU4X → .so/.dylib/.dll。而 Flathub 构建沙箱完全离线，无法 直接 cargo build 下载依赖——这正是 上篇 Flathub 博客 中踩过的坑。可行的绕过方案有两种：一是按官方推荐的流程预先编译各平台 二进制并随源码入库；二是在 flatpak-builder manifest 中手动添加 Rust vendoring + offline 编译模块。无论哪种，都大幅增加了 Flatpak 打包的维护复杂度。
• 实验阶段：当前稳定版 0.17.0，API 仍在迭代，icu4x Dart 绑定更是只有 0.0.1 稳定版，实际依赖 pre-release（2.2.0-dev.3）
• 重量级依赖：仅为了 collation 功能，需要引入整个 i18n 框架（datetime、number、plural、case mapping 等），对只需要字符串排序的场景是明显的过度引入

结论：功能最强、官方背书，但太重且 Flathub 打包维护成本高，且自身（截至 2026-08）来说还没有进入稳定版本的 Release，使用风险大。

2.7. 方案 E：调用平台原生排序引擎

每个操作系统都已经内置了成熟的排序引擎——Android 有 android.icu.text.Collator， iOS/macOS 有 localizedStandardCompare:，Linux 有 libicui18n， Windows 有 CompareStringEx，Web 有 Intl.Collator^[4]。

这些 API 一直在系统后台默默工作——Finder 按名称排列文件、Android 文件管理器排序、 Windows 资源管理器排序，靠的都是它们。那能不能直接调它们呢？

这个方案走的是混合路线：桌面端优先用 FFI（同步）直调系统库， 移动端用 Platform Method（异步）桥接原生 API，对外统一封装为 Future 接口。 Linux 走 FFI→libicui18n，Windows FFI→ICU DLL 优先、Pigeon→CompareStringEx 作为 fallback， Android/iOS/macOS 因为文档没暴露 FFI 友好的公开 collation 入口，出于维护性考虑走平台桥接。

优点：

• 零额外体积：不打包任何 collation 数据，直接调用 OS 内置 API
• 系统一致性：排序结果与系统文件管理器完全一致
• 自动更新：collation 数据随 OS 更新自动改善，无需升级包版本
• Flathub 友好：无额外下载/编译依赖，纯 Dart + Pigeon/FFI 调用系统 API
• 全平台：Flutter 支持的主流平台都有成熟的系统级 collation API

缺点：

• 需要为每个平台编写不同的桥接代码（FFI / Platform Method）
• 部分平台需要异步调用：Android/iOS/macOS 走平台通道（异步）， 这意味着不能直接把比较函数传给 List.sort()。 不过 Linux（FFI→ICU）和 Windows（FFI→ICU DLL）在底层是同步的—— 为了 API 一致性，包对外统一返回 Future，上层按异步处理即可
• 不同平台的 API 行为可能有细微差异
• 需要在 Dart 侧做统一的错误处理和 Degrade Fallback

结论：这个方案轻量、Flathub 兼容好，体积小，是一个很好的平衡点，适合对多平台统一没有对决掌控力需求，但希望可以快速获得自然语言排序能力或者希望可以和系统体验尽量一致的应用。

3. 落地

3.1. 阶段一：在 mhabit 内部实现平台封装

确定了方案 E 之后，第一件事不是立刻创建独立 package—— 而是先在应用内部把各平台的排序调用跑通，验证方案的可行性。

实现的核心思路：

• 在 Dart 侧定义一个统一的排序接口（SortItem + NativeSort.sort()）
• 桌面端通过 Dart FFI 直调系统 collation 库
  • Linux→libicui18n
  • Windows→ICU DLL，也提供 Pigeon fallback（CompareStringEx）
• 移动端则通过 Pigeon（Android/iOS/macOS）桥接原生 API

NativeSort (Dart API)
├── Android   → Pigeon → android.icu.text.Collator
├── iOS       → Pigeon → localizedStandardCompare:
├── macOS     → Pigeon → localizedStandardCompare:
├── Linux     → Dart FFI → system libicui18n
├── Windows   → Pigeon (CompareStringEx) 或 FFI (ICU)
└── Web       → Dart → Intl.Collator

3.2. 阶段二：提取为独立 package

在自己项目内部跑通后，发现这段代码有三个理由值得独立为 Publish Package：

1. pub.dev 上没有类似的全平台原生排序方案。collection.compareNatural 只解决数字排序， intl4x 太重且实验性——在「轻量、全平台、原生排序」这个细分定位上，存在明显的空白。

2. Flathub 兼容是刚需。mhabit 已经上架 Flathub，任何需要额外下载/编译的依赖都是不可接受的。 而 intl4x/icu4x 正是需要额外 FFI 编译，处理需要 Patch 或者预编译，相当麻烦和脆弱，已经在 sqlite3 package 上踩过坑。

3. 解耦与复用。排序逻辑与业务无关，独立出去后可以单独测试、独立发版， 其他 Flutter 项目也可以直接引用。

于是 native_natural_sort 便顺势出现了。

3.3. mhabit 项目接入

mhabit 接入 native_natural_sort 的改动集中在几个文件。

参考 lib/main.dart:

await NativeSort().config(
  SortOptions(
    windows: SortOptionsWindows.ffi(onLoadFailed: WindowsSort.pigeon),
  ),
);

在 main() 中做一次性初始化。Windows 上配置了 FFI（ICU）→ Pigeon（CompareStringEx）的双后端 fallback。

参考 lib/extensions/collation_extensions.dart， 封装了一个通用的 naturalSort<T> 扩展方法，接收 idOf/valueOf 函数来适配任意数据类型：

extension NaturalSortExtension on NativeSort {
  Future<List<T>> naturalSort<T>({
    required List<T> items,
    required String Function(T) idOf,
    required String Function(T) valueOf,
    bool descending = false,
    String? locale,
  }) async {
    if (items.isEmpty) return items;
    final sortItems = items
        .map((e) => SortItem(id: idOf(e), value: valueOf(e)))
        .toList();
    final sorted = await sort(sortItems, /* ... */);
    // Map sorted IDs back to original items.
    // ...
  }
}

在 ViewModel 层，排序逻辑通过 SortGuard 做了 degrade fallback：

• 当 natural sort 启用且排序方式是「按名称」时，走异步的原生排序路径
• 如果异步排序失败（如平台 API 异常），自动退回到 compareTo 默认排序，保证功能不崩溃
• SortGuard 确保并发重排请求只保留最新一次的结果

参考 lib/pages/habits_display/_providers/habit_summary.dart 中 _ResortHandler：

class _ResortHandler {
  FutureOr<_HabitsSortableCache> call() {
    final needHabitNatural =
        cache.sortType == HabitDisplaySortType.name &&
        _vm._naturalSortEnabled;
    final needGroupNatural = /* ... */;

    if (!needHabitNatural && !needGroupNatural) return defaultSort();
    return _guardedNaturalSort(needHabitNatural, needGroupNatural);
  }
}

同时还通过 NaturalSortExperimentalFeature 提供了一个开关， 让用户可以自行选择是否启用原生排序（默认开启）。

3.4. 异步改造：SortGuard 模式

方案 E 的混合路线带来了一个工程上的实际问题： Linux/Windows 的 FFI 排序在底层是同步的，但 Android/iOS/macOS 的 Pigeon 排序是异步的。 为了 API 一致性，native_natural_sort 对外统一返回 Future。 这意味着原有的同步排序逻辑——所有方案 A~D 都能直接 list.sort(compareFn) ——需要异步化改造。

mhabit 的做法是引入 SortGuard——一个简单的基于计数的排序守卫。 核心思路：

• 每次数据重载前调用 _sortGuard.bump()，递增代数
• 排序时用 _sortGuard.run() 包装，捕获当前代数
• 异步排序完成后比对代数——如果不一致，说明数据已变，结果作废

参考 lib/common/sort_generation.dart：

class SortGuard {
  int _generation = 0;

  void bump() { _generation++; }

  FutureOr<T?> run<T>(FutureOr<T> Function() sort) {
    final token = _generation;
    final result = sort();
    return result is Future<T>
        ? result.then((r) => _generation == token ? r : null)
        : (_generation == token ? result : null);
  }
}

在 ViewModel 中，_resortData() 的返回类型从 void 改为 FutureOr<void>—— 同步路径（默认排序）直接返回，异步路径（原生排序）返回 Future， 调用方用 await _resortData() 统一处理，接口不变。

配合 .catchError((e) => defaultSort()) 的 degrade fallback， 异步改造对上层完全透明。

3.5. 最终效果

接入 native_natural_sort 后，按名称排序的结果对比：

可以看到前面提到的问题都得到了很好的解决。

4. 总结

回头看整个过程，核心教训是：字符串排序看似简单，一旦涉及多语言用户，就不要自己造轮子。

Unicode Collation Algorithm（UCA）是一个发展了数十年的标准，各操作系统已经内置了经过充分测试的实现。 与其打包 ICU 数据或依赖实验性框架，直接调用 OS 原生 API 是更务实的选择——0体积增长（无需维护 ICU Database）、系统级正确性、随 OS 更新自动改善。

该 Package 目前已在 pub.dev/native_natural_sort 发布，如果你也在做多语言 Flutter 应用且遇到了类似的问题，希望这个 Package 能有所帮助。

参考文献

1. Unicode Collation Algorithm (UCA) — Wikipedia
2. Abjad numerals — Wikipedia
3. Natural sort order — Wikipedia
4. Intl.Collator — MDN Web Docs

1. 背景

Table Habit 的发布自动化已经通过 fastlane 覆盖了 Android（Google Play）和 iOS/macOS（App Store）——Android 侧配置见 android/fastlane/Fastfile，iOS/macOS 同理。接下来推进 Windows / Microsoft Store。

最初的设想是：Windows 这边也应该能找到类似 fastlane 的现成方案直接套上去。结果翻了一圈官方文档和社区项目，并没有找到一个等价物——最后能用的就是 Microsoft 官方的 msstore CLI，剩下的部分（账号配置、CI 拼装）都得自己手动走一遍。

落地 CI 之前需要先确认两件事：

1. 应用必须已在 Partner Center 中创建，拿到应用 ID（Product ID）并在 GitHub 中配置 ——这个值跟 iOS/macOS 的 Bundle ID 一样是公开标识。
2. 代表 CI 的 Microsoft Entra ID 应用注册（App Registration）必须在 合作伙伴中心（Partner Center） 分配「经理 (Windows)」角色。

下面先走一遍 Partner Center + Entra ID + msstore CLI 的手动配置流程，再落地代码。最终 CI 落地的成品见：

• _submit-windows-store.yml
• build_windows_store
• scripts/build_msix_store.cmd
• scripts/msstore/check_draft_ownership.ps1
• scripts/msstore/update_changelog.ps1

2. 合作伙伴中心（Partner Center）账号侧配置

2.1. 关联 Microsoft Entra ID 租户（Tenant）

可能很多独立开发者跟我一样以为关联 Entra ID 租户（Tenant，以前叫 Azure AD）需要公司账号——其实 个人开发者账号也能关联 Entra ID 租户，官方文档明确支持个人账号事后关联 Entra ID 做多用户管理。具体操作步骤：

1. 用注册合作伙伴中心（Partner Center）开发者账号的同一个 Microsoft 账号登录 entra.microsoft.com——账号一致，后面关联起来省事。
2. 左侧导航找「标识」→「概述」，或者直接搜”创建租户”，进入创建向导后租户类型选 Microsoft Entra ID（不是面向终端用户的 Entra External ID/B2C，那个是给应用做用户认证用的，跟这里的 CI 场景没关系）。
3. 填写组织名称、初始域名（格式固定是 <自定义前缀>.onmicrosoft.com，全局唯一，先到先得）和国家/地区，提交创建。

   第一次提交的时候撞上了 Error Code: 715-123280，换浏览器、清缓存都没用，一度以为是 provisioning 流程被自动校验挡住的已知问题。后来发现根本原因是当前登录的 Microsoft 账号邮箱本身就没法用来创建 Entra ID 租户——换一个邮箱重新登录、重新提交就解决了。如果你也撞上这个错误码，先试试换邮箱。

4. 创建过程中会要求绑定一张信用卡——按 Microsoft Entra ID Free 官方说明，这张卡只用于身份验证，是 Entra ID Free 的强制步骤，照提示填实际卡信息即可。
5. 流程一般几分钟就能跑完，完成后页面会自动切到新租户。记下这个租户的域名和 Tenant ID。
6. 回到合作伙伴中心，点右上角齿轮图标 → 「帐户设置」，左侧导航「组织配置文件」分组下选 Tenants（这一项没有被本地化，显示的就是英文原文）→「将 Microsoft Entra ID 与合作伙伴中心账号关联」，用第 5 步那个租户里的账号登录确认域名信息，点「确认」完成关联（详见官方文档 Associate an existing Microsoft Entra ID tenant）。关联完成后，合作伙伴中心才能在 2.3 里识别到这个租户下创建的 App Registration。

详见 Microsoft Entra ID 文档。

2.2. 创建 CI 用的应用注册（App Registration）

在 Entra ID 租户里创建一个应用注册（App Registration）代表 CI，具体操作步骤（详见 应用注册快速入门）：

1. 登录 entra.microsoft.com，确认当前租户已经切到 2.1 里新建的那个（右上角齿轮图标可以切换租户）。

2. 左侧导航找到「应用注册」，点击「新注册」。

   

3. 填写一个能区分用途的名称（比如 mhabit-windows-store-ci）；「受支持的帐户类型」选 仅单个租户——这个 app 只代表自己的 CI，不需要兼容多租户或个人账号登录。

4. 「重定向 URI」整段留空——CI 走的是客户端凭据流程（client credentials flow），靠 Client ID + Secret 直接换 token，没有用户登录跳转这一步，不需要配回调地址。

   

5. 点击「注册」，进入应用的概述页，记下 目录(租户) ID 和 应用程序(客户端) ID——这两个就是后面要用的 Tenant ID 和 Client ID。

   

6. 左侧导航切到「证书和密码」→「客户端密码」→「新客户端密码」，填写「说明」和「截止期限」（官方推荐 180 天/6 个月），点击「添加」。

   

7. 添加完成后客户端密码列表会多出一行，「值」这一列就是 Client Secret，只在这一次完整显示——当场复制保存，刷新或离开页面之后就只剩打码后的样子。注意旁边的「机密 ID」不是密码本身，只是这条密码记录的标识符，别认错。

   

2.3. 给 App 分配「经理 (Windows)」角色

回到 Partner Center，路径是 Account settings → User management → Microsoft Entra applications → Add Microsoft Entra application，把上一步创建的 app 加进来并分配角色（详见 Partner Center 文档）。

角色分配是个多选框——经理 (Windows)、开发人员、业务参与者、财务参与者、营销人员——很容易纠结要不要多选几个才保险。实际上官方文档只要求 经理 (Windows) 一个角色，它的权限范围本身已经覆盖”开发人员”能做的操作。

2.4. 获取卖家 ID（MSSTORE_SELLER_ID）

这是我踩的最迷惑的一个坑。Partner Center 的”标识符”（Identifiers）页面会列出 Windows 发布者 ID（CN=... 格式，是包签名身份的 Publisher CN）、Windows Phone 发布者 ID、Symantec ID——这里面 没有一个是 Seller ID。

这个命名上的混淆连官方 msstore-cli 的 issue 里都有人在问，文档里笼统说的 “Publisher ID / Seller ID” 和 Partner Center 页面上的实际字段名对不上，第一次确实很难找。

3. 本机 msstore CLI 配置

至此账号侧需要的 4 个值都齐了（租户 ID / Tenant ID、应用程序(客户端) ID / Client ID、客户端密码 / Client Secret、卖家 ID / Seller ID），接下来在本机装 msstore CLI 完成认证。

我的环境是 macOS，所以需要先有 .NET 9 Runtime，然后：

brew install microsoft/msstore-cli/msstore-cli

安装完成后跑 reconfigure 把凭证写进本机配置：

msstore reconfigure \
  --tenantId <TENANT_ID> \
  --sellerId <SELLER_ID> \
  --clientId <CLIENT_ID> \
  --clientSecret <CLIENT_SECRET>

• TENANT_ID：2.2 第 5 步的「目录(租户) ID」
• SELLER_ID：2.4 节的 Seller ID
• CLIENT_ID：2.2 第 5 步的「应用程序(客户端) ID」
• CLIENT_SECRET：2.2 第 7 步的客户端密码「值」

认证完成后用 apps list 获取 Product ID，需要跟仓库 README 里已经公开的 Microsoft Store 徽章链接（apps.microsoft.com/detail/<PRODUCT_ID>）做一次比对，确认没取错应用：

msstore apps list

...
✅ Retrieved Managed Applications
┌───┬──────────────┬──────────────┬─────────────────────┐
│   │ ProductId    │ Display Name │ PackageId           │
├───┼──────────────┼──────────────┼─────────────────────┤
│ 1 │ 9N********GZ │ Table Habit  │ Friesi23.TableHabit │
└───┴──────────────┴──────────────┴─────────────────────┘

4. 写进 GitHub Environment

至此拿到了 5 个值，但 Secrets 和普通变量需要分别处理：

没什么好说的，4 个 Secret 自己在终端里敲，PRODUCT_ID 因为不是凭证直接用 gh variable set 写进去就行。 另外我将所有 KV 都写入了 store-submission 环境，具体放在 repo 全局还是环境都可以。

5. CI 落地

落地成 composite action + reusable workflow，方便跟仓库里现有的几个发布 job 拼装。

新增 composite action build_windows_store：复用 setup_flutter，构建命令直接调本机开发者也会跑的 scripts/build_msix_store.cmd，把 Store 身份参数（--identity-name/--publisher 等）集中写在脚本里，避免在 action 和脚本之间重复一份。--store 模式下 msix 不需要本地签名（Microsoft Store 提交时会自行重新签名），所以这个 action 没有签名相关的 input，跟 build_windows（GitHub Release 用，要 PFX 签名）完全独立。

新增 _submit-windows-store.yml：workflow_call + dry_run 输入，environment: store-submission。用官方 microsoft/microsoft-store-apppublisher action 装 CLI、reconfigure 写认证，然后是后面”坑”里提到的草稿归属校验（check_draft_ownership.ps1）——校验通过才会触发耗时的 Windows 构建，没必要为一个不属于这条 CI 的草稿白跑一次构建。publish 永远带 --noCommit，是否真正执行 submission publish 完全交给 dry_run 控制。最后一步用后面”坑”里那个细粒度 PAT，把这次的 submission ID 写回 Environment Variable，留给下一次 CI 跑时做归属校验。

修改 release-app.yml：加一个跟 build-windows-msix 并行的 submit-windows-store job，只 needs: pre-build，不进 post-build 的 needs 链。另外加了一条 if：pre-release 的 tag 直接跳过——Microsoft Store 没有公开的 beta 渠道（package flights/私有受众都是邀请制），pre-release 没有地方可提交。

修改 manual-submit.yml：加 windows 输入（skip/submit 二选一，没有 track 概念）和对应 job，直接调用，不需要 resolve-apple-store-track 那一套。

# _submit-windows-store.yml (part)
on:
  workflow_call:
    inputs:
      dry_run:
        type: boolean
        default: false

jobs:
  submit-windows-store:
    runs-on: windows-2022
    environment: store-submission
    steps:
      - uses: actions/checkout@v6
      - name: Setup Microsoft Store Developer CLI
        uses: microsoft/microsoft-store-apppublisher@v1.3
      - name: Configure Microsoft Store Developer CLI
        shell: pwsh
        env:
          MSSTORE_TENANT_ID: ${{ secrets.MSSTORE_TENANT_ID }}
          MSSTORE_SELLER_ID: ${{ secrets.MSSTORE_SELLER_ID }}
          MSSTORE_CLIENT_ID: ${{ secrets.MSSTORE_CLIENT_ID }}
          MSSTORE_CLIENT_SECRET: ${{ secrets.MSSTORE_CLIENT_SECRET }}
        run: >
          msstore reconfigure
          --tenantId $env:MSSTORE_TENANT_ID
          --sellerId $env:MSSTORE_SELLER_ID
          --clientId $env:MSSTORE_CLIENT_ID
          --clientSecret $env:MSSTORE_CLIENT_SECRET
      # 校验当前 Partner Center 上 pending 的草稿是不是上一次 CI 自己创建
      # 的，不是就跳过，避免覆盖人工在 Partner Center 准备中的草稿。
      - id: ownership
        name: Check pending submission ownership
        shell: pwsh
        run: >
          scripts\msstore\check_draft_ownership.ps1
          -ProductId "${{ vars.MSSTORE_PRODUCT_ID }}"
          -KnownSubmissionId "${{ vars.MSSTORE_LAST_CI_SUBMISSION_ID }}"
      - id: build
        if: ${{ steps.ownership.outputs.proceed == 'true' }}
        uses: ./.github/actions/build_windows_store
      - name: Stage package
        if: ${{ steps.ownership.outputs.proceed == 'true' }}
        shell: pwsh
        env:
          MSIX_PATH: ${{ steps.build.outputs.msix-path }}
        run: msstore publish $env:MSIX_PATH -id ${{ vars.MSSTORE_PRODUCT_ID }} --noCommit
      - id: changelog
        name: Stage changelog metadata
        if: ${{ steps.ownership.outputs.proceed == 'true' }}
        shell: pwsh
        run: >
          scripts\msstore\update_changelog.ps1
          -ProductId "${{ vars.MSSTORE_PRODUCT_ID }}"
      - name: Finalize submission
        if: ${{ steps.ownership.outputs.proceed == 'true' && !inputs.dry_run }}
        shell: pwsh
        run: msstore submission publish ${{ vars.MSSTORE_PRODUCT_ID }}
      - name: Record CI-owned submission Id
        if: ${{ steps.ownership.outputs.proceed == 'true' }}
        shell: pwsh
        env:
          GH_TOKEN: ${{ secrets.MSSTORE_VARS_PAT }}
        run: >
          gh variable set MSSTORE_LAST_CI_SUBMISSION_ID
          --body "${{ steps.changelog.outputs.submission-id }}"
          --env store-submission
          --repo ${{ github.repository }}

坑

代码写完、真实 CI 跑起来之后，又踩了几个一开始没预料到的坑。下面按时间顺序记录。

setup_flutter 在 cmd 步骤里找不到 flutter/dart

根因很简单但藏得很深：共享 action setup_flutter 把 "<目录>:$PATH" 整行写进了 $GITHUB_PATH。bash 步骤”凑巧”能工作（bash 按 : 拆 PATH），但 Windows cmd 步骤只认 ; 作为路径分隔符，整行 : 直接被当成目录名的一部分，自然找不到 flutter/dart。

之前四个 build_* action 全部用的 bash 步骤，这个 bug 从来没暴露过——Windows Store 这条是第一个用 cmd 步骤跑裸 flutter/dart 命令的消费方。修法也简单：

只写目录本身（去掉 :$PATH），对其余四个调用无影响。

msstore CLI 输出的 JSON 不能直接 ConvertFrom-Json

msstore submission get 会把 JSON 当人类可读的文本来打印——按终端列宽强制换行。如果输出里有长的中文字段（编码成 \uXXXX 转义），换行边界刚好切到转义序列中间，PowerShell 把多行拼回去再 ConvertFrom-Json 就会报 Invalid Unicode escape sequence。

本机用同一个真实账号能稳定复现一模一样的截断位置，确认不是网络波动或 CI 特有。修法是截取第一个 { 到最后一个 } 之间，再去掉所有原始换行——JSON 在 token 之间本来就不在乎空白，真正的换行应该被编码成 \n 两个字符，不会是裸换行。

# 示意：截取 { 到 } 之间再去除裸换行
# $raw = msstore submission get ...
# $json = ($raw -join '') -replace '...'

这种设计缺陷在非 ASCII 内容上几乎是必现的。

官方文档摘要的字段名是错的

网上摘要写的是 listings[language].whatsNew，但真实账号读出来的是 Listings.<lang>.BaseListing.ReleaseNotes（legacy API 的 PascalCase 形状）。

草稿归属标记走了三个方案才落地

CI 需要一种方式来判断”当前线上是否已经有本次构建对应的草稿”，避免重复创建。这个标记存在哪里，前后试了三个方案：

这里有个方法论上的教训：”字段技术上可写” ≠ “适合用来存自动化标记”——选状态存储位置时，要先确认谁会看到这个字段，而不是只确认能不能写进去。Description 就是典型的反例：能写，但用户可见，风险太高。

最终落地为两个 PowerShell 脚本：

• check_draft_ownership.ps1 负责比对当前草稿 ID 与已知的 CI 归属标记
• update_changelog.ps1 负责写入 changelog 并回写归属标记

两个脚本都可以脱离 CI 在本机直接跑，跟 fastlane lane 的用法一致。

细粒度 PAT 第一次配的权限类别选错了

gh variable set --env store-submission ... 需要 PAT 有写入权限。第一次配的时候以为勾上 “Variables: read and write” 就够了，结果真实跑直接报 403。查了文档才发现：Environment 级的 Variable 接口（带 --env 参数那种）实际归在 “Environments” 这个权限类别下，跟仓库/组织级 Variable 用的 “Variables” 类别是两个独立的勾选项——这个分类非常不直观，很容易选错而不自知。把 “Environments” 也勾上（保留原来的 “Variables”，两个都给 Read and write）之后才跑通。

总结

最终整体流程其实就是账号配置 → CLI 认证 → 写 Environment → CI 落地这四步，账号部分卡住的点基本都在第一步，代码部分的坑全在最后一步，中间两步反而是最顺利的。

参考资料

1. msstore-cli—Microsoft Store CLI
2. Quickstart: Register an application—Microsoft identity platform
3. Microsoft Entra service principal—Partner Center
4. Microsoft Entra ID Free—Microsoft Cost Management
5. Associate an existing Microsoft Entra ID tenant with your Partner Center account

因此在这里记录一下完整的配置过程：从硬件选型、本地模型部署、MCP 服务器接入，到 Continue 和 Copilot 插件的联动使用。

版本说明：本文基于 VS Code 1.124.0（内置 Copilot）和 Continue 1.3.38 编写，插件更新较快，部分界面和配置项可能随版本变化。

这篇文章分为两大部分：AI 编码助手配置和 MCP 服务器配置，两者同等重要——前者决定 AI 的能力上限，后者决定 AI 能调用哪些工具。 希望能帮到同样想在本机跑 AI 编码助手的朋友。

1. 为什么需要本地 AI + MCP

云端 AI 编码助手（如 GitHub Copilot、Cursor 等）已经非常强大了，但有几个场景我还是倾向于本地方案：

• 隐私敏感项目：有些代码实在不愿意上传到第三方服务。
• 定制化工具链：通过 MCP（Model Context Protocol）把本地命令、数据库查询、项目特定知识暴露给 AI，这是云端方案做不到的。
• 成本可控：本地模型推理不产生 API 调用费用，对重度用户来说长期来看更划算。

2. 机器配置与实际模型选型

最近选模型的时候踩了不少坑，最大的教训就是：别光看”参数量”这个数字，硬件瓶颈才是决定日常体验的关键。

本地跑模型，核心瓶颈有两个：一是内存容量（决定能装多大的模型），二是内存带宽（决定 token 吐出来的速度）。 下面以我手头的两台机器和实际使用的模型为例，结合硬件参数和体感体验给出选型建议。

2.1. 桌面机：RTX 4090 + i7-14700 + 64GB

这台机器通过 LM Studio 暴露本地服务，是日常编码的主力。RTX 4090 的 24GB GDDR6X 显存配合约 1008 GB/s 的内存带宽，在消费级显卡里属于第一梯队。

我在这台机器上主要使用的模型：

这里有一个值得展开的坑：qwen3-coder 30b 虽然激活参数只有 3.3B，但体感上 token 生成速度并不理想。 原因不在于”激活参数少就快”——MoE 架构每层要选哪些”专家”参与计算，而且 30B 的总参数量意味着每次推理都要从显存读取全部专家权重，实际内存访问量远大于 3.3B 对应的理论值（一点私货：选模型时别被”激活参数”这个数字骗了，总参数对内存压力的影响更大）。

相比之下，gemma4 26b 同样是 MoE 架构（25.2B 总参 / 3.8B 激活），但磁盘占用更小（17 GB vs 19 GB），”专家选择”的开销相对更低，体感明显更流畅。

强烈建议在 24GB 显存的机器上，优先选 17-20 GB 量级的模型，留出 4-7 GB 给上下文和运行时开销。 超过 20 GB 的模型虽然能塞进显存，但一旦上下文变长，就容易触发 CPU offload，速度会断崖式下降。

2.2. MacBook Pro：M4 Pro + 48GB 统一内存

这台机器通过 Ollama 本地使用，适合移动办公和深度分析场景。M4 Pro 的统一内存带宽约 200 GB/s，只有 RTX 4090 的五分之一左右，但 48GB 容量是实打实的优势。

我在这台机器上实际使用的模型：

M4 Pro 的内存带宽虽然弱，但 MLX 格式对 Apple Silicon 有原生优化， qwen3.6 35b-mlx 的推理体验比同量级 GGUF 格式好不少。 对于需要更强推理能力的场景（比如复杂架构设计、多文件重构）， 35B 稠密模型在 MacBook 上的表现反而比 4090 上跑 27B 更有深度。

2.3. 关于 CPU offload 的取舍

当模型大小超过 GPU 显存时，推理框架会把部分计算任务挪到系统内存， 由 CPU 分担。这个策略的代价很大：

• RTX 4090 + 64GB DDR5：GPU 和系统内存之间靠 PCIe 总线通信，理论带宽约 64 GB/s，只有显存带宽的六分之一。一旦触发 offload， token 生成速度会从每秒几十个降到个位数。
• M4 Pro 统一内存：GPU 和 CPU 共享同一条内存总线，不存在”跨设备搬运数据”的问题，offload 的惩罚远小于桌面方案。

因此我的经验法则是：

• 桌面端：模型 + 上下文尽量控制在显存以内，宁可换小一点的模型也不要触发 offload。
• Mac 端：统一内存架构下 offload 惩罚较小，可以大胆用更大的模型，用容量换推理深度。

2.4. 跨设备工作流

结合两台机器的特点，我的实际分工是：

• 桌面端（4090）：qwen3.6 27b 做日常编码主力，gemma4 26b 做备选。响应速度快，适合高频交互。
• MacBook（M4 Pro）：qwen3.6 35b-mlx 做深度分析，deepseek-coder-v2 16b 做移动办公时的日常编码。
• 轻量任务：hermes3 8b 或 qwen2.5-coder 1.5b，两台机器都能秒回，适合快速问答和简单补全。

两者通过同一套 VS Code 配置（Continue + MCP）无缝衔接，只需切换 apiBase 地址。

3. 本地模型部署方案选型

在配置插件之前，需要先跑通本地模型服务。目前个人开发者最常用的方案是 Ollama 和 LM Studio，下面将两者的适用范围和上手难度做一个对比。

3.1. Ollama

Ollama 是目前最轻量的本地模型部署工具，支持 macOS 和 Windows 平台。安装方式很简单：

# macOS 安装
brew install ollama

# Windows 安装（winget）
winget install Ollama.Ollama

# Windows 安装（choco）
choco install ollama

安装后一条命令即可拉取模型并启动服务（默认 11434 端口）：

ollama pull qwen2.5:14b
ollama serve

Ollama 的模型库覆盖了主流开源模型，量化版本（如 q4_k_m）对显存要求也比较友好。

我从实际使用角度说几个体会：Ollama 虽然提供了 GUI，但功能比较简陋，可配置项不多。 如果想自定义模型（比如调整系统提示词或改变采样参数），得手写 Modelfile 然后 ollama create 重新生成模型，server 端也不能通过界面调参，只能命令行附加环境变量。 但这反过来也让它很适合自动化场景：CI 流水线里一条 ollama pull 就能拉起服务，和脚本联动也很方便，不需要额外处理 GUI 进程。

3.2. LM Studio

LM Studio 同样支持 macOS 和 Windows，提供了一个完整的 GUI 界面，模型下载、加载、对话都在图形界面里完成。

# macOS 安装
brew install --cask lm-studio

# Windows 安装（winget）
winget install LM-Studio.lm-studio

# Windows 安装（choco）
choco install lm-studio

和 Ollama 相反，LM Studio 的参数调优可以在界面里通过滑块完成，不需要手写配置文件。如果想对比不同模型的效果，直接在 GUI 里切换就行。

但我实际使用中也有几个感受：LM Studio 的 GUI 虽然方便，但也带来了额外开销，资源占用比 Ollama 稍重。 更关键的是，把它集成到 CI 或自动化脚本里不太容易——比如我想通过脚本控制模型加载、调整参数、再启动服务，LM Studio 没有像 Ollama 那样干净的命令行接口，和 shell 脚本联动的成本比较高。

3.3. 两者的取舍

两者都提供了 server 能力，但设计取向不同。Ollama 偏向命令行和自动化，CI 集成友好，自定义程度高但需要手动写 Modelfile 并重新创建模型。LM Studio 偏向交互体验，GUI 可配置项多，但高度自定义（比如和脚本联动）相对不容易。

我手头的分工是：桌面端（4090）用 LM Studio 暴露服务，因为日常编码时通过 GUI 调参更直观；MacBook 上用 Ollama，因为移动场景下我更看重轻量，而且 ollama pull 在终端里一条命令就能搞定。

两者暴露的 API 端口略有不同：Ollama 默认 http://localhost:11434，LM Studio 默认 http://localhost:1234（OpenAI 兼容模式）。 后续章节以 Ollama 为例，但 LM Studio 的配置思路完全一致，只需替换 apiBase 地址即可。

4. Continue 插件配置

Continue 是一个开源的 AI 编码助手插件，支持接入任意模型提供商（包括本地 Ollama 和 LM Studio）。这是本文 AI 配置部分的核心。

4.1. 安装与基础配置

在 VS Code 扩展市场安装 Continue 后，配置文件通常位于 ~/.continue/ 目录或工作区根目录的 .continue/config.yaml。

4.2. 模型配置

Continue 的模型配置是整篇配置的核心。结合前文两台机器的硬件特点和模型选型，下面将按角色拆分配置。

4.2.1. Chat 模型

Chat 模型用于对话面板的深度交互，是日常使用频率最高的角色。我根据两台机器分别配置了本地和云端（Home Cloud）两套模型：

models:
  # —— 本地 Ollama（MacBook M4 Pro）——
  - name: Qwen3.6 35B (Local)
    provider: ollama
    model: qwen3.6:35b-mlx
    roles:
      - chat
    capabilities:
      - tool_use
      - image_input
    defaultCompletionOptions:
      contextLength: 65536

  # —— Home Cloud LM Studio（桌面 RTX 4090）——
  - name: Qwen3.6 27B (Home Cloud)
    provider: lmstudio
    model: qwen/qwen3.6-27b
    apiBase: http://<internal-hostname>:1234/v1
    apiKey: sk-lm-<PLACEHOLDER>
    requestOptions:
      timeout: 120000
    roles:
      - chat
    capabilities:
      - tool_use
      - image_input

  - name: Qwen3.6 35B (Home Cloud)
    provider: lmstudio
    model: qwen/qwen3.6-31b-qat
    apiBase: http://<internal-hostname>:1234/v1
    apiKey: sk-lm-<PLACEHOLDER>
    requestOptions:
      timeout: 120000
    defaultCompletionOptions:
      contextLength: 65536
    roles:
      - chat
    capabilities:
      - tool_use
      - image_input

  - name: Gemma4 26B (Home Cloud)
    provider: lmstudio
    model: google/gemma-4-26b-a4b-qat
    apiBase: http://<internal-hostname>:1234/v1
    apiKey: sk-lm-<PLACEHOLDER>
    requestOptions:
      timeout: 120000
    defaultCompletionOptions:
      contextLength: 32768
    roles:
      - chat
    capabilities:
      - tool_use
      - image_input

  # —— 其他角色模型（edit/apply/autocomplete/embed/rerank）见下文 ——
  # - name: ...
  #   ...

几个配置细节值得说明：

• roles: [chat]：明确声明该模型用于对话角色。Continue 支持 chat / edit / apply / autocomplete / embed / rerank 等角色，一个模型可以兼任多个角色。
• capabilities：tool_use 表示模型支持工具调用（即 MCP 工具），image_input 表示支持图片输入。 不是所有模型都支持这些能力，配置时根据模型实际能力勾选即可。
• contextLength：上下文窗口大小。qwen3.6 系列原生支持 65536 的上下文，而 gemma4 26b 我设为 32768—— 桌面端显存有限，上下文太长容易触发 CPU offload（见 2.3 节）。
• requestOptions.timeout：LM Studio 远程调用设置了 120 秒超时，因为桌面端模型较大，复杂问题推理时间可能较长。

4.2.2. Edit 和 Apply 模型

Edit 角色负责在编辑器中直接修改代码，Apply 角色将修改应用到文件。这两个角色对代码理解能力要求较高，我选了 qwen3-coder 30b：

models:
  - name: Qwen3 Coder 30B (Local)
    provider: ollama
    model: qwen3-coder:30b
    roles:
      - chat
      - edit
      - apply
    capabilities:
      - tool_use
    defaultCompletionOptions:
      temperature: 0.7
      contextLength: 32768

  - name: Qwen3 Coder 30B (Home Cloud)
    provider: lmstudio
    model: qwen/qwen3-coder-30b
    apiBase: http://<internal-hostname>:1234/v1
    apiKey: sk-lm-<PLACEHOLDER>
    requestOptions:
      timeout: 120000
    defaultCompletionOptions:
      contextLength: 32768
    roles:
      - chat
      - edit
      - apply
    capabilities:
      - tool_use

  # —— 其他角色模型（chat/autocomplete/embed/rerank）见上文/下文 ——
  # - name: ...
  #   ...

qwen3-coder 在代码生成和修改方面表现突出，虽然前文提到它在 4090 上的 token 生成速度一般， 但 edit/apply 场景不需要高频交互，深度更重要。temperature: 0.7 让输出在创造性和稳定性之间取得平衡。

4.2.3. 自动补全模型

自动补全对响应速度要求极高，模型太大反而影响体验。我选了 qwen2.5-coder 1.5b——虽然只有 1.5B 参数， 但针对代码任务做了专门训练，补全质量完全够用：

models:
  - name: Qwen2.5 Coder 1.5B (Local)
    provider: ollama
    model: qwen2.5-coder:1.5b
    roles:
      - autocomplete
    capabilities:
      - tool_use
    autocompleteOptions:
      disable: false
      maxPromptTokens: 1024
      debounceDelay: 250
      modelTimeout: 150
      maxSuffixPercentage: 0.2
      prefixPercentage: 0.3
      onlyMyCode: true

  # —— 其他角色模型（chat/edit/apply/embed/rerank）见上文/下文 ——
  # - name: ...
  #   ...

autocompleteOptions 的几个关键参数：

• maxPromptTokens: 1024：限制每次补全请求的上下文大小，避免把整个文件都发给模型。
• debounceDelay: 250：输入停止 250ms 后再触发补全，避免打字过程中频繁请求。
• modelTimeout: 150：150ms 超时——补全要快，超时了就放弃，别让用户等。
• onlyMyCode: true：只索引用户自己的代码文件，不扫描 node_modules 等第三方库，减少噪音。

4.2.4. 嵌入和重排序模型

嵌入模型用于代码库的向量检索，重排序模型对检索结果进行精排。两者配合可以让 AI 更准确地找到项目中的相关代码：

models:
  - name: Nomic Embed Text V1.5 (Local)
    provider: ollama
    model: nomic-embed-text:v1.5
    roles:
      - embed
    embedOptions:
      maxChunkSize: 512
      maxBatchSize: 4

  - name: Huggingface-tei Reranker (Local)
    provider: huggingface-tei
    model: tei
    apiBase: http://localhost:18082
    apiKey: <PLACEHOLDER>
    roles:
      - rerank

  # —— 其他角色模型（chat/edit/apply/autocomplete）见上文 ——
  # - name: ...
  #   ...

nomic-embed-text 只有 274 MB，几乎不占资源，但检索效果出乎意料地好。 Huggingface TEI（Text Embeddings Inference）重排序服务跑在本地 18082 端口， 对检索结果做二次排序后，AI 引用代码的准确率有明显提升。

4.3. 上下文提供者配置

Continue 的 context 配置决定了 AI 能访问哪些本地信息源。以下是我的配置：

context:
  - provider: code
  - provider: diff
  - provider: terminal
  - provider: open
    params:
      onlyPinned: true
  - provider: clipboard
  - provider: tree
  - provider: debugger
    params:
      stackDepth: 3
  - provider: repo-map
    params:
      includeSignatures: false
  - provider: os

这些上下文提供者的作用：

强烈建议不要把所有上下文提供者都打开——每个提供者都会增加 prompt 的 token 消耗， 按需启用即可。比如 debugger 只在调试场景下有用，平时可以关掉。

4.4. 跨设备无缝切换

两套模型配置（本地 Ollama + Home Cloud LM Studio）的好处是：

• 在 MacBook 上：优先使用本地 Ollama 模型，不依赖网络。
• 在桌面端：通过 apiBase 连接桌面 LM Studio 服务，用 4090 的算力。
• 桌面机宕机时：MacBook 上的本地模型可以无缝接管，不影响工作。

切换不需要改配置——Continue 会在 Chat 面板里列出所有可用模型，下拉菜单选一个就行。

4.5. 核心功能

• Chat 面板：在编辑器侧边栏直接与模型对话，支持引用当前文件内容和选中代码。
• Tab 自动补全：基于本地模型的代码补全，配置 autocomplete 角色后生效。
• 自定义指令：通过 .continue/rules 定义项目级编码规范，让 AI 输出符合你的风格。

4.6. MCP 服务器配置

Continue 的 MCP 服务器配置独立于 VS Code 用户级 mcp.json，位于 ~/.continue/mcpServers/vscode-mcp.json。 下面是我实际使用的两个 MCP 服务器：

$ cat ~/.continue/mcpServers/vscode-mcp.json
{
  "mcpServers": {
    "filesystem": {
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ],
      "autoApprove": "true",
      "command": "npx"
    },
    "context7": {
      "name": "context7",
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ]
    }
  }
}

• filesystem 服务器让 AI 能直接读写当前工作区文件。
• context7 则提供了额外的上下文检索能力，适合在大型项目中快速定位相关代码。

注意 Continue 的 MCP 配置和 VS Code 内置的 mcp.json 是两套独立体系，前者给 Continue 用，后者给 Copilot 用。 两者可以同时启用，AI 工具会根据当前使用的插件选择对应的 MCP 服务器。

5. Copilot 模型与 MCP 配置

GitHub Copilot 从 2025 年起开始支持 MCP 服务器接入，这意味着你可以将本地工具直接暴露给 Copilot。 和 Continue 类似，Copilot 的配置也分为两部分：先配置模型（config），再配置 MCP 服务器。

5.1. Config 配置

Copilot 的模型配置现在可以通过 VS Code 内置的 UI 界面完成，无需手动编辑 JSON 文件。 具体流程如下：

1. 点开 Copilot Chat 聊天输入框底部的模型选择下拉菜单，在列表最下方的 “Other” 选项旁点击 齿轮图标（Manage Language Models）。

2. 在打开的界面中点击右上角的 “Add Models” 按钮，并在下拉菜单中选择 “Custom Endpoint”。

   

3. 输入模型的群组名称（Group Name，如 LM-Studio）并回车。
4. 随后输入该端点的显示名称（Display Name）并回车，接着系统会提示输入 API Key（由于是本地 LM Studio，这里可以随便输入任意非空字符串，比如 “lm-studio” 或 “not-needed”）并回车。
5. 接着选择 API 类型，本地 LM Studio 通常选择 “Chat Completions”。
6. 填完这些后，VS Code 会自动打开 chatLanguageModels.json 配置文件。你只需在 models 数组中将 "url" 改为 http://localhost:1234/v1，并将 "id" 改为你在 LM Studio 中加载的具体模型 ID，保存并关闭文件即可。
7. 回到聊天面板的模型下拉菜单中，选中刚刚添加的本地模型开始使用。

配置完成后，VS Code 会将配置写入 ~/Library/Application Support/Code/User/chatLanguageModels.json（macOS）。 一个典型的配置文件如下：

[
  {
    "name": "Copilot",
    "settings": {},
    "vendor": "copilot"
  },
  {
    "name": "Ollama",
    "url": "http://localhost:11434",
    "vendor": "ollama"
  },
  // LM-Studio
  {
    "apiKey": "<PLACEHOLDER>",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "google/gemma-4-31b-qat",
        "maxInputTokens": 32000,
        "maxOutputTokens": 16000,
        "name": "Gemma4 31B",
        "toolCalling": true,
        "url": "http://<internal-hostname>:1234/v1",
        "vision": true
      },
      {
        "id": "qwen/qwen3.6-27b",
        "maxInputTokens": 64000,
        "maxOutputTokens": 16000,
        "name": "Qwen3.6 27B",
        "toolCalling": true,
        "url": "http://<internal-hostname>:1234/v1",
        "vision": true,
        "defaultCompletionOptions": {
          "temperature": 0.2,
          "topP": 0.9
        }
      }
    ]
  }
]

几个配置细节值得说明：

• vendor: "copilot"：GitHub 官方的云端模型服务，无需额外配置 API Key，开箱即用。
• vendor: "ollama"：本地 Ollama 服务，只需指定 url 即可接入，和 Continue 的 Ollama 配置思路一致。
• vendor: "customendpoint"：自定义端点（如 LM Studio），需要配置 apiKey、apiType 以及具体的模型列表。
• toolCalling：标记该模型支持工具调用（即 MCP 工具）。只有开启这个选项，Copilot 才能调用 MCP 服务器暴露的工具。
• vision：标记该模型支持图片输入，适合多模态场景。
• defaultCompletionOptions：采样参数，如 temperature 和 topP。temperature: 0.2 让输出更稳定，适合代码生成场景。

我的实际配置中，桌面端（4090）通过 Custom Endpoint 接入了 LM Studio 上的 qwen3.6 27b 和 gemma4 31b， MacBook 上则通过 Ollama 接入了本地的 qwen3.6 35b-mlx。切换模型时，在 Copilot Chat 面板的下拉菜单里选一个就行——

5.2. MCP 服务器配置

Copilot 的 MCP 能力通过 VS Code 用户级 mcp.json 实现，当 MCP 服务器启动后，Copilot 会自动发现可用工具。 没什么好说的，配好 mcp.json 就能用。

一个典型的 mcp.json 如下：

{
  "servers": {
    "github-mcp": {
      "type": "http",
      "url": "https://example.com/mcp/",
      "gallery": "https://example.com/gallery",
      "version": "1.0.0"
    },
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  },
  "inputs": []
}

配置分为两类启动方式：

• HTTP 类型：通过 type: "http" 指定远程 MCP 端点，适合云端服务。
• 命令类型：通过 command + args 本地启动进程，适合本地工具。

注意 Continue 的 MCP 配置（~/.continue/mcpServers/）和 VS Code 内置的 mcp.json 是两套独立体系，前者给 Continue 用，后者给 Copilot 用。 两者可以同时启用，AI 工具会根据当前使用的插件选择对应的 MCP 服务器。

5.3. 与 Continue 的分工

两者不是替代关系，更像是互补。下面列了一个对比表：

我的使用习惯是：日常编码靠 Copilot 的行级补全降低输入成本，遇到复杂问题切换到 Continue 用本地模型做深度对话—— 代码不会离开本机，这点对我来说很重要。

6. 实际工作流

结合两个插件和 MCP 服务器，一个典型的本地 AI 开发工作流如下：

1. 日常编码：Copilot 提供行级补全，降低输入成本。
2. 复杂问题：切换到 Continue，使用本地模型进行深度对话，代码不会离开本机。
3. 工具调用：通过 MCP 服务器，AI 可以直接执行本地命令、查询数据库、读取项目文档。
4. 规则约束：通过项目级指令文件，确保 AI 输出符合团队规范。

7. 需要注意

MCP 服务器无法启动

这是最常见的问题，排查步骤：

• 检查 mcp.json 的 JSON 语法是否正确，一个多余的逗号就能让整个配置失效。
• 查看 VS Code 日志：~/Library/Application Support/Code/logs/<session>/mcpServer.*.log，日志里通常会有明确的错误信息。
• 确认 command 字段对应的可执行文件在 PATH 中，可以用 which 命令验证。

模型响应慢

• 检查显存是否充足，考虑使用量化模型（如 q4_k_m）。
• 调整 num_ctx 参数以控制上下文窗口大小，上下文越大推理越慢。
• 如果用的是 LM Studio，可以在界面里直接调参，比较直观。

Continue 与 Copilot 补全冲突

两者可以同时启用，但 Tab 补全只能由一个提供。在 Continue 配置中设置 tabAutocompleteModel 后， Continue 会接管补全功能。如果你希望 Copilot 继续提供补全，把 Continue 里的 tabAutocompleteModel 去掉就行。

a. LM Studio 加载配置实践

上面提到了 qwen3.6 27b 是桌面端的主力模型，下面补充一下在 LM Studio 中的具体加载配置。 这部分内容比较细，但实际体验下来，正确的参数设置对显存占用和推理速度影响很大。

模型来源：从 Hugging Face 下载 unsloth/Qwen3.6-27B-GGUF，推荐 UD-Q4_K_XL 量化版本（次选 UD-Q4_K_M）。 注意不要下载带 mmproj 的版本——那是视觉组件，白占约 0.9 GB 显存，纯文本任务用不上。

LM Studio 加载参数：

预计显存占用（24 GB RTX 4090）：

• 模型权重：~17 GB
• KV Cache（Q8 @ 64K）：~2 GB
• CUDA overhead：~1 GB
• 合计约 20 GB，余量约 4 GB，日常编码够用 ✅

Agent 模式补充：Thinking mode 单次输出可达 32K–81K tokens，这是爆显存的主要原因。 建议在 Inference Parameters → Max Tokens 设为 ≤ 16384，或者在 system prompt 里加一句 Keep your thinking concise. 来限制输出长度。

b. 词汇表

本文涉及的部分专业术语，供快速查阅。

Token：大模型处理文本的基本单位。可以粗略理解为”字”或”词碎片”—— 一个英文单词通常是一个 token，一个汉字可能是一个或半个 token。 模型的上下文窗口大小、生成速度等通常以 token 数为单位。

内存带宽（Memory Bandwidth）：内存每秒能传输的数据量，单位通常是 GB/s。 带宽越高，模型从内存读取权重的速度越快，token 生成也就越快。 可以类比为”水管粗细”——水管越粗，单位时间流过的水越多。

显存（VRAM, Video RAM）：GPU 的专用内存，类似于 CPU 的系统内存但带宽更高。 模型推理时权重数据需要加载到显存中，显存大小决定了你能跑多大的模型。 RTX 4090 的显存为 24GB，而 MacBook 的统一内存则同时充当显存和系统内存。

模型架构：本文主要涉及两种——

• 稠密（Dense）：模型的所有参数在每次推理时都参与计算。参数量越大，推理越慢，但通常质量更高。
• MoE（Mixture of Experts，混合专家）：模型内部有多个”专家”子网络，每次推理只激活其中一部分。总参数量可以很大，但实际参与计算的参数较少。理论上更高效，但实际表现取决于具体实现。

激活参数（Active Parameters）：MoE 模型中，每次推理实际参与计算的参数量。 注意：虽然激活参数决定计算量，但总参数仍会影响内存带宽压力，因为全部权重都需要从内存中读取。

CPU Offload：当模型太大、放不下 GPU 显存时，推理框架会把部分计算层”卸载”到系统内存中，由 CPU 分担计算。 由于系统内存带宽远低于显存带宽，offload 后推理速度会明显下降。在统一内存架构（如 Apple Silicon）上，这个惩罚较小。

统一内存（Unified Memory）：Apple Silicon（M 系列芯片）的内存架构，CPU 和 GPU 共享同一块物理内存，不存在传统 PC 上”显存”和”系统内存”的分离。 好处是模型不会受限于显存大小，代价是内存带宽低于独立显卡。

MLX 格式：Apple MLX 推出的机器学习框架原生模型格式，针对 Apple Silicon 的 GPU 和神经网络引擎做了硬件级优化。 同量级模型，MLX 格式在 Mac 上的推理速度通常优于 GGUF 格式。

GGUF 格式：大模型通用的量化模型文件格式（GGML 的继任者），被 Ollama、LM Studio 等主流推理工具支持。 跨平台兼容性好，但在 Apple Silicon 上的加速效果不如 MLX 格式。

参考资料

• Continue - Plugin
• GitHub Copilot
• Qwen
• Gemma
• Nomic Embed Text

最近路由器上的 OpenVPN 证书到期了。

续签的时候突然意识到：维护一整套 PKI 证书体系对于家庭 VPN 场景来说实在有些过重——既要管 CA，又要管客户端证书吊销，过期了还得记得手动续签。 作为家庭环境，真的没必要搞得这么复杂。

我很懒，因此决定换成 WireGuard。理由很简单：

• WireGuard 现在已经足够成熟，主流平台（Android、iOS、Windows、macOS、Linux）都有官方或社区维护的客户端
• 连接体验比 OpenVPN 轻快不少
• 代码量少、易于审计，而且本身就是 FOSS（GPLv2），正合我意

故在这里简单记录一下在 OpenWrt 23.05 上配置 WireGuard 服务器的过程，以及踩过的几个坑。

1. 环境说明

• OpenWrt 版本：23.05
• WireGuard 相关包：wireguard、wireguard-tools、kmod-wireguard
• 路由器型号：FriendlyElec NanoPi R6S

2. 安装 WireGuard

opkg update
opkg install wireguard wireguard-tools kmod-wireguard

踩坑提醒：谨慎安装 wg-installer-server

在 OpenWrt 上部署 WireGuard 时，我曾安装 wg-installer-server 来简化配置， 但后续遇到了比较难排查的问题：

• wg0 接口最初工作正常；
• WireGuard 路由能够正确创建；
• 运行一段时间后，wg0 接口和相关路由会被自动删除；
• VPN 连接随之失效；
• 问题表现得像是 WireGuard 配置错误，但实际上并非如此。

排查后发现，问题并不在 WireGuard 本身， 而是在 wg-installer-server 附带的自动化管理逻辑。 该软件包除了生成配置外，还会安装额外的 hotplug 脚本， 并可能与动态路由组件（如 Babel、OLSR 等）产生交互， 从而自动修改网络配置。

对于普通家庭 VPN、自建回家网络等场景， 强烈建议直接使用以下三个包即可：

• kmod-wireguard
• wireguard-tools
• luci-proto-wireguard（如需 LuCI 界面管理）

尽量避免引入额外的自动化管理层。 如果遇到 WireGuard 配置明明正确， 但接口或路由会被自动修改、删除的情况， 可以优先检查是否安装了 wg-installer-server 或类似的一键安装工具。

3. 配置 WireGuard 服务端

3.1. 创建接口配置

编辑 /etc/config/network，添加 WireGuard 接口配置。 以下以 LuCI 界面操作和 uci 命令行两种方式说明。

通过 LuCI 界面配置

1. 进入 网络 → 接口 → 新建接口
2. 接口名称填 wg0，接口类型选 WireGuard VPN

3. 常规设置下填写以下参数：

   

   参数	说明	示例值
   私钥	点击 “生成新的密钥对”	<YOUR_PRIVATE_KEY>
   公钥	点击 “生成新的密钥对”	<YOUR_PUBLIC_KEY>
   监听端口	WireGuard 服务监听的 UDP 端口	51820
   IP 地址	服务端在 WireGuard 虚拟网络中的 IP	10.0.1.1/24
   无主机路由	不添加主机路由，服务器下不要勾选

4. 防火墙设置下区域选择 lan：

   

   可选：如需对 VPN 流量做更精细的防火墙控制， 可暂不将 wg0 加入 lan 区域，转而在第 4 节创建独立的防火墙区域。

通过 uci 命令行配置

# 1. 生成 WireGuard key 并写入文件（可选保留）
umask 077
wg genkey | tee /etc/wireguard/wg0_private.key | wg pubkey > /etc/wireguard/wg0_public.key

# 2. 读取 private key 并直接写入 UCI
PRIVATE_KEY=$(cat /etc/wireguard/wg0_private.key)

uci set network.wg0=interface
uci set network.wg0.proto='wireguard'
uci set network.wg0.listen_port='51820'
uci set network.wg0.private_key="$PRIVATE_KEY"
uci set network.wg0.addresses='10.0.1.1/24'

# 3. 防火墙：加入 LAN 区域（关键）
#    如需独立防火墙区域，可跳过此步，转至第 4 节配置
LAN_ZONE=$(uci show firewall | grep "=zone" | grep "name='lan'" | cut -d. -f2 | cut -d= -f1)

uci add_list firewall.$LAN_ZONE.network='wg0'

# 4. 应用配置
uci commit network
uci commit firewall

/etc/init.d/network restart
/etc/init.d/firewall restart

注意：WireGuard 虚拟接口的 IP 地址段不要与服务端所在局域网同网段， 否则会导致路由冲突，客户端无法正常访问内网资源。详见后文的坑点说明。

3.2. 启动服务

ifdown wg0 && ifup wg0

重启接口后，可以通过以下命令验证接口是否正常工作：

wg show

正常输出应类似如下：

interface: wg0
  public key: <SERVER_PUBLIC_KEY>
  private key: (hidden)
  listening port: 51820

4. 防火墙配置（可选：独立区域方案）

默认方案已够用

在上文第 3 节中，我们已将 wg0 加入 lan 防火墙区域—— 对于大多数家庭 VPN 场景，这已经足够：客户端可以正常访问内网和外网。

本节提供一个可选的高级方案：为 WireGuard 创建独立的防火墙区域。 该方案参考了 upsangel 的文章， 适合需要对 VPN 流量做更精细控制（如限制访问范围、独立日志等）的场景。 如果默认方案工作正常，可以跳过本节。

注意：如果采用独立区域方案，需要将第 3 节中将 wg0 加入 lan 区域的配置移除， 否则 wg0 会同时属于两个区域，可能导致规则冲突。

下面将介绍独立区域方案的配置方法。 该方案共需配置三个部分：

4.1. 通过 LuCI 界面配置

1. 进入 网络 → 防火墙 → 区域，新建 wireguard 区域

   

   1. 将 wg0 接口分配给该区域
   2. 输入 / 输出 / 转发策略均设为 接受（Accept）
   3. 启用 MSS 钳制（MSS Clamping / mtu_fix） 以避免分片导致的连接不稳定
   4. 添加转发规则：wireguard → lan 以及 lan → wireguard

2. 进入 网络 → 防火墙 → 端口转发，新建 wireguard 规则：

   

   字段	值
   名称	wireguard
   协议	UDP
   源区域	wan
   外部端口	51820
   目标区域	lan
   内部 IP	192.168.1.1（替换为路由器实际 LAN IP）
   内部端口	51820

3. 进入 网络 → 防火墙 → 通信规则，新建 Allow-WireGuard 规则：

   

   字段	值
   名称	Allow-WireGuard
   协议	UDP
   源区域	wan
   目标区域	设备（输入）
   目标端口	51820
   动作	接受

4.2. 通过 uci 命令行配置

没什么好说的，直接上命令：

# 第 1 步 — 创建 WireGuard 专属防火墙区域（Zone Settings）
uci add firewall zone
uci set firewall.@zone[-1].name='wireguard'
uci add_list firewall.@zone[-1].network='wg0'
uci set firewall.@zone[-1].input='ACCEPT'
uci set firewall.@zone[-1].output='ACCEPT'
uci set firewall.@zone[-1].forward='ACCEPT'
uci set firewall.@zone[-1].mtu_fix='1'

# 允许 wireguard ↔ lan 双向转发
uci add firewall forwarding
uci set firewall.@forwarding[-1].src='wireguard'
uci set firewall.@forwarding[-1].dest='lan'

uci add firewall forwarding
uci set firewall.@forwarding[-1].src='lan'
uci set firewall.@forwarding[-1].dest='wireguard'

# 第 2 步 — 将 WAN UDP 51820 映射到本机（Port Forward）
uci add firewall redirect
uci set firewall.@redirect[-1].name='wireguard'
uci set firewall.@redirect[-1].src='wan'
uci set firewall.@redirect[-1].proto='udp'
uci set firewall.@redirect[-1].src_dport='51820'
uci set firewall.@redirect[-1].dest='lan'
uci set firewall.@redirect[-1].dest_ip='192.168.1.1'   # 替换为路由器实际 LAN IP
uci set firewall.@redirect[-1].dest_port='51820'
uci set firewall.@redirect[-1].target='DNAT'

# 第 3 步 — 放行 WAN 入站 UDP 51820（Traffic Rule）
uci add firewall rule
uci set firewall.@rule[-1].name='Allow-WireGuard'
uci set firewall.@rule[-1].src='wan'
uci set firewall.@rule[-1].proto='udp'
uci set firewall.@rule[-1].dest_port='51820'
uci set firewall.@rule[-1].target='ACCEPT'

# 提交并重启防火墙
uci commit firewall
/etc/init.d/firewall restart

至此，独立区域方案的配置就完成了。流量路径如下：

外网客户端
  → WAN UDP 51820
  → Traffic Rule 放行
  → Port Forward 映射到本机
  → wg0 接口处理 WireGuard 握手
  → Zone Forwarding 打通 wireguard ↔ lan
  → 访问 192.168.1.x 内网设备

5. 配置 WireGuard 客户端

下面介绍两种为客户端生成配置的方式：通过 LuCI 界面（适合快速导出二维码）和通过 uci 命令行。 两种方式最终都会得到一份客户端可用的 .conf 配置。

5.1. 通过 LuCI 界面配置

1. 进入 网络 → 接口 → wg0 → 对端配置

2. 点击 添加对端，填写以下参数：

   

   参数	说明	示例值
   描述	客户端设备标识	my-phone
   公钥	客户端的 WireGuard 公钥；也可点击 “生成新的密钥对” 由路由器代为生成	<CLIENT_PUBLIC_KEY>
   私钥	若需导出完整配置给客户端使用，需填入客户端私钥；导出完成后可删除此项	<CLIENT_PRIVATE_KEY>
   预共享密钥	额外一层对称加密（后量子安全增强）；可点击 “生成” 自动生成	<PRESHARED_KEY>
   允许的 IP	客户端在 WireGuard 网络中的 IP 地址	10.0.1.2/32
   路由允许的 IP	勾选后客户端可访问路由器上的其他网段（如 lan）	勾选
   持久保活	保持连接活跃，穿 NAT 时有用	25

   提示：若客户端尚无任何配置，推荐直接在路由器上点击 “生成新的密钥对” 代为生成密钥， 这样可避免在客户端手动执行命令。

3. 保存后点击底部的 生成配置 按钮，系统将弹出一个二维码界面。 打开手机上的 WireGuard App，选择 “扫描二维码” 即可快速导入配置。

   

   注意：每个客户端设备需要单独添加一个对端参数，不能多个设备共用同一组密钥。 导入配置后，建议返回对端配置界面将 “私钥” 字段清空，以免敏感信息留在路由器配置中。

5.2. 通过 uci 命令行配置

# 1. 生成客户端密钥对
umask 077
wg genkey | tee /etc/wireguard/client_private.key | wg pubkey > /etc/wireguard/client_public.key

# 2. 读取客户端公钥
CLIENT_PUBLIC_KEY=$(cat /etc/wireguard/client_public.key)

# 3. 在 wg0 接口下添加对端（Peer）
uci add network wireguard_wg0
uci set network.@wireguard_wg0[-1].description='my-phone'
uci set network.@wireguard_wg0[-1].public_key="$CLIENT_PUBLIC_KEY"
uci set network.@wireguard_wg0[-1].allowed_ips='10.0.1.2/32'
uci set network.@wireguard_wg0[-1].route_allowed_ips='1'
uci set network.@wireguard_wg0[-1].persistent_keepalive='25'

# 4. 生成预共享密钥（可选，但推荐）
PRESHARED_KEY=$(wg genpsk)
uci set network.@wireguard_wg0[-1].preshared_key="$PRESHARED_KEY"

# 5. 应用配置
uci commit network
/etc/init.d/network restart

若需手动生成客户端 .conf 文件（例如通过 SCP 传给客户端），可参考以下模板：

cat > /tmp/wireguard-client.conf <<'EOF'
[Interface]
PrivateKey = <CLIENT_PRIVATE_KEY>
Address = 10.0.1.2/32
DNS = 10.0.1.1

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
PresharedKey = <PRESHARED_KEY>
Endpoint = <YOUR_SERVER_DOMAIN_OR_IP>:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25
EOF

配置项说明：

5.3. 连接测试

配置导入客户端后，启用连接并执行以下验证：

# 查看路由表，确认流量经过 wg0
ip route get 8.8.8.8

# 测试内网访问
ping 192.168.1.1

# 测试外网访问
ping 8.8.8.8

同时在路由器端检查 WireGuard 状态：

# 查看接口及 Peer 信息
wg show

# 查看接口详情
ip addr show wg0

# 查看路由表
ip route show

wg show 的输出能直接反映客户端连接状态及传输流量，是验证配置是否生效的最快方式。

6. 客户端链接配置

服务端配置完成后，下面介绍在 Android 和 macOS 上配置 WireGuard 客户端的方法。

6.1. Android

Android 端推荐使用 WireGuard 官方 App（Google Play / F-Droid）。

1. 安装 WireGuard App 后，点击右下角 + 号
2. 选择 从二维码扫描 或 从本地文件导入
   • 若使用 LuCI 界面配置（第 5.1 节），可直接扫描路由器生成的二维码
   • 若使用命令行配置（第 5.2 节），将 .conf 文件传至手机后选择导入
3. 导入后点击右上角开关启用连接
   • 

提示：Android 10 及以上版本支持 WireGuard 作为系统级 VPN， 连接后所有流量（包括其他 App）都会经过 VPN 隧道。 若只需部分流量走 VPN，可在 App 设置中调整 AllowedIPs。

6.2. macOS

macOS 端推荐使用 WireGuard 官方客户端（App Store）。

1. 从 App Store 安装 WireGuard
2. 打开 App，点击左下角 + 号
3. 选择 导入隧道接口…
   • 从路由器导出 .conf 文件，或手动粘贴配置内容
4. 导入后点击右侧开关启用连接

注意：macOS 客户端默认会将所有流量路由至 VPN（AllowedIPs = 0.0.0.0/0）。 若只需访问内网资源，将 AllowedIPs 改为内网网段（如 192.168.1.0/24）即可。

可选替代方案：如果你不想通过 App Store 安装， 可以使用 mintc2/wireguard-macos-app， 这是一个非 App Store 打包的 WireGuard macOS 客户端， 功能与官方版本一致，可直接从 GitHub Releases 下载。

7. 排错

7.1. 常见问题排查

8. 关键坑点

8.1. Peer IP 地址不要与局域网同网段

问题描述：WireGuard 虚拟接口分配的 IP 地址如果与服务端所在局域网处于同一网段， 会导致路由冲突，客户端无法正常访问内网资源。

示例对比：

建议：为 WireGuard 选择一个完全独立的私有网段， 如 10.x.x.x 或 172.16.x.x。

参考资料

1. 一键连回家内网：OpenWrt 上部署 WireGuard VPN 服务器的三个要点 — upsangel
2. OpenWrt 安装 WireGuard — iyzm
3. OpenWrt 搭建 WireGuard VPN — mingyue5826
4. OpenWrt 安装 WireGuard — 6xyun

为了方便在 Windows 上进行开发，Flavor 的存在很有必要，所以有了这篇文章。下面将介绍通过使用环境变量来达到类似 --flavor 的效果。

1. 在 CMake 中引入 Flavor 环境变量

CMake 中可以读取当前构建的环境变量，FLutter flavor 使用 FLUTTER_APP_FLAVOR 环境变量处理不同的 Flavor， 不过我们不能使用这个变量，会提示这些变量由 Flutter 框架管理，构建无法进行。 因此这里使用 APP_FLAVOR_WIN 进行区分，将以下内容按需添加到 windows/CMakeLists.txt 中：

set(APP_NAME "<YOUR_APP_NAME>")
add_definitions(-DAPP_NAME="${APP_NAME}")

if(DEFINED ENV{APP_FLAVOR_WIN})
  # CMake 中定义 FLAVOR 区分不同的 flavor
  set(FLAVOR "$ENV{APP_FLAVOR_WIN}")
  # 将其引入 cpp 编译中
  add_definitions(-DFLAVOR="${FLAVOR}")
  # 下面区分不同的 flavor，请按照自己要求进行添加/删除/修改
  if(FLAVOR STREQUAL "f_dev")
    # 定义 FLAVOR_NAME，这里作为 FLAVOR 的别名用于区分路径，后面会用到
    set(FLAVOR_NAME "dev")
    # 引入 APP_TITLE_SUFFIX，用于在 cpp 中修改 windows title，后面会用到
    add_definitions(-DAPP_TITLE_SUFFIX=" - ${FLAVOR_NAME}")
  # elseif(FLAVOR STREQUAL "f_store")
  #   set(FLAVOR_NAME "store")
  # elseif(FLAVOR STREQUAL "f_generic")
  #   set(FLAVOR_NAME "")
  else()
    # 不支持的 flavor 就报错退出，当然也可以设置默认值不退出
    message(FATAL_ERROR "Flavor:${FLAVOR} is not support, abort CMake.")
  endif()
  message("Building Windows with flavor: '${FLAVOR}'")
  # 和 flutter 现有支持的 flavor 风格保持相同，将不同的 flavor 最终构建目录进行区分
  # 注意：flutter run 只支持默认构建目录，其他目录不被识别，后面将使用软链进行处理
  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/runner/Debug-${FLAVOR}")
  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/runner/Release-${FLAVOR}")
endif()

2. 根据不同 Flavor 处理相关内容

为 windows 引入 flavor 的初衷是 path_provider 在 windows 上的路径由 windows/runner/Runner.rc 中的配置确定， 具体为 %AppData%\Roaming\<CompanyName>\<ProductName>，比如 %AppData%\Roaming\io.github.friesi23\mhabit。

而这导致默认开发时启动的应用也会读取实际使用时的用户数据，这显然不合理。一个直观的方案是在代码中进行处理，不过这显然很不优雅， 我希望能够获得在 macos 或者 linux 上一样的开发体验（macos 上拥有 flavor，linux 在分发时可以通过各种容器方案比如 appimage 或者 flatpak 对配置进行隔离）。 因此本节内容主要用于解决 path_provider 对应的路径问题，如果由其他需求也可以通过下面的内容举一反三。

首先修改 windows/runner/Runner.rc 文件，将其命名为 windows/runner/Runner.rc.in，然后内部修改如下：

// ...
    BLOCK "StringFileInfo"
    BEGIN
        BLOCK "040904e4"
        BEGIN
            VALUE "CompanyName", "<org.example.company>" "\0"
            VALUE "FileDescription", "{FILE_DESCRIPTION}" "\0"
            VALUE "FileVersion", VERSION_AS_STRING "\0"
            VALUE "InternalName", "{INTERNAL_NAME}" "\0"
            VALUE "LegalCopyright", "Copyright (C) 2024 io.github.friesi23. All rights reserved." "\0"
            VALUE "OriginalFilename", "<app>.exe" "\0"
            VALUE "ProductName", "{PRODUCT_NAME}" "\0"
            VALUE "ProductVersion", VERSION_AS_STRING "\0"
        END
    END
// ...

将 FileDescription，InternalName，ProductName 使用占位符进行替换，然后修改 windows/runner/CMakeLists.txt，添加如下内容：

set(ORIGINAL_RC "Runner.rc.in")
set(GENERATED_RC "Runner.rc")
file(READ ${ORIGINAL_RC} RC_CONTENT)
# FLAVOR_NAME 在 windows/CMakeLists.txt 中定义
# 下面代码的工作是对占位符进行替换
if(FLAVOR_NAME)
    string(REPLACE "{PRODUCT_NAME}" "${BINARY_NAME}-${FLAVOR_NAME}" RC_CONTENT "${RC_CONTENT}")
    string(REPLACE "{FILE_DESCRIPTION}" "${BINARY_NAME}-${FLAVOR_NAME}" RC_CONTENT "${RC_CONTENT}")
    string(REPLACE "{INTERNAL_NAME}" "${BINARY_NAME}-${FLAVOR_NAME}" RC_CONTENT "${RC_CONTENT}")
else()
    string(REPLACE "{PRODUCT_NAME}" "${BINARY_NAME}" RC_CONTENT "${RC_CONTENT}")
    string(REPLACE "{FILE_DESCRIPTION}" "${BINARY_NAME}" RC_CONTENT "${RC_CONTENT}")
    string(REPLACE "{INTERNAL_NAME}" "${BINARY_NAME}" RC_CONTENT "${RC_CONTENT}")
endif()
# 写入 windows/runner/Runner.rc 保证路径与修改前一致
file(WRITE ${GENERATED_RC} "${RC_CONTENT}")

同文件找到 add_executable(${BINARY_NAME} WIN32 ... 调用，并修改如下：

# 将 "Runner.rc" 替换为 GENERATED_RC 变量，主要为了保持代码一致，逻辑上当然也可以不改
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "${GENERATED_RC}"
  "runner.exe.manifest"
)

至此已经可以让构建流程根据 APP_FLAVOR_WIN 变量达到 flavor 的效果，下面一节会解决 flutter run 的问题。

3. 兼容标准 flutter 相关命令

在第一节中修改 windows/CMakeLists.txt 中包含如下：

  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/runner/Debug-${FLAVOR}")
  set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/runner/Release-${FLAVOR}")

这会将构建后的产物输出至非标准目录，而由于 flutter 本身没有实际支持 windows 下的 flavor， 因此相关执行程序需要寻找的目录是固定的，即 build\windows\<ARCH\runner\Release(Debug)。

可以简单注释掉这两条命令来规避问题，但会导致本地每次构建不同 flavor 时都需要重新构建。如果希望和标准的 --flavor 行为保持一致， 一个可行的方案是使用软链将输出目录指向标准目录，具体操作如下：

1. 在 windows/CMakeLists.txt 下增加如下命令，作用为每次构建前删除软链，防止无 Flavor 时写入错误的目录：

   function(safe_remove path)
     if(IS_SYMLINK "${path}")
       message("Removing symlink: ${path}")
       file(REMOVE "${path}")
     # elseif(EXISTS "${path}")
     #   message("Removing directory: ${path}")
     #   file(REMOVE_RECURSE "${path}")
     endif()
   endfunction()
   
   if(DEFINED FLAVOR)
     # safe_remove("${CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG}")
     # safe_remove("${CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE}")
   else()
     safe_remove("${CMAKE_BINARY_DIR}/runner/Debug")
     safe_remove("${CMAKE_BINARY_DIR}/runner/Release")
   endif()
   

2. 在 windows/runner/CMakeLists.txt 下增加如下命令，用于在构建完成后创建软链：

   if(FLAVOR)
     add_custom_command(TARGET ${BINARY_NAME} POST_BUILD
       COMMAND ${CMAKE_COMMAND} -E rm -rf
         "$<IF:$<CONFIG:Debug>,${CMAKE_BINARY_DIR}/runner/Debug,${CMAKE_BINARY_DIR}/runner/Release>"
       COMMAND ${CMAKE_COMMAND} -E create_symlink
         "$<IF:$<CONFIG:Debug>,${CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG},${CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE}>"
         "$<IF:$<CONFIG:Debug>,${CMAKE_BINARY_DIR}/runner/Debug,${CMAKE_BINARY_DIR}/runner/Release>"
     )
   endif()
   

至此，完成所有构建流程的修改。

4. 使用不同的 Flavor 进行构建

上面修改完成后，我们便可以使用如下命令为不同 Flavor 进行构建：

$env:APP_FLAVOR_WIN=<YOUR_FLAVOR_NAME>
flutter build windows
# ...
# Building Windows with flavor: <YOUR_FLAVOR_NAME>
# Building Windows application...
# √ Built build\windows\x64\runner\Release\<app>.exe
Remove-Item Env:\APP_FLAVOR_WIN

Flavor 构建后的目录结构如下（以 arch=x86_64 build=release 为例）：

build\windows\x64\runner\Release-<YOUR_FLAVOR_NAME>
build\windows\x64\runner\Release --> build\windows\x64\runner\Release-<YOUR_FLAVOR_NAME>

当然无 Flavor 的构建也是允许的：

flutter build windows
# ...
# Building Windows application...
# √ Built build\windows\x64\runner\Release\<app>.exe

4.1. vscode launcher 配置

如果使用 vscode 进行开发，可以考虑在 launch.json 中增加如下内容，方便调试使用：

{
  {
    "name": "debug (<YOUR_FLAVOR_NAME>)",
    "request": "launch",
    "type": "dart",
    "flutterMode": "debug",
    "args": [
      "--flavor",
      "<YOUR_FLAVOR_NAME>"
    ],
    "env": {
      "APP_FLAVOR_WIN": "<YOUR_FLAVOR_NAME>"
    }
  },
  {
    "name": "profile (<YOUR_FLAVOR_NAME>)",
    "request": "launch",
    "type": "dart",
    "flutterMode": "profile",
    "args": [
      "--flavor",
      "<YOUR_FLAVOR_NAME>"
    ],
    "env": {
      "APP_FLAVOR_WIN": "<YOUR_FLAVOR_NAME>"
    }
  },
  {
    "name": "release (<YOUR_FLAVOR_NAME>)",
    "request": "launch",
    "type": "dart",
    "flutterMode": "release",
    "args": [
      "--flavor",
      "<YOUR_FLAVOR_NAME>"
    ],
    "env": {
      "APP_FLAVOR_WIN": "<YOUR_FLAVOR_NAME>"
    }
  },
}

如此便可以获得兼顾 windows linux macos 三端的统一运行配置。

5. 总结

完整修改可以参考“该 PR”，里面缺少了 Profile 的支持， 如有需要也可以很方便的进行添加。

F1. 为不同的 Flavor 修改对应的 Windows Title

在第一节中，我们使用 -D 传递了一些定义，可以在 windows 的入口处使用。 定位到 windows/runner/main.cpp，增加并修改如下：

#ifndef APP_NAME
#define APP_NAME L"<YOUR_DEFAULT_APP_NAME>"
#endif

#ifdef APP_TITLE_SUFFIX
#define WINDOW_TITLE APP_NAME APP_TITLE_SUFFIX
#else
#define WINDOW_TITLE APP_NAME
#endif

// ...
//if (!window.Create(L"<YOUR_DEFAULT_APP_NAME>", origin, size)) {
  if (!window.Create(L"" WINDOW_TITLE, origin, size)) {
    return EXIT_FAILURE;
  }
  window.SetQuitOnClose(true);
// ...

升级流程

参考：

• Software & Update Management
• Migrate to OMV7

# 保证当前 omv 是最新的
omv-upgrade
# 升级到下一版本
omv-release-upgrade

强烈建议在 TTY 而不是 SSH 下运行该命令，因此中途网络环境变更可能导致 SSH 链接断开。 最好使用外界屏幕操作，如果是无头服务器可以使用 tmux 或 screen。

omv-release-upgrade 执行时间比较长，请保证计算机没有关闭（踩坑了），等待执行完毕即可。

问题：安装被意外中断

如果没有 UPS 或者遭到其他任何性质导致 omv-release-upgrade 命令执行过程中断， 大概率会导致升级不完全，此时如果已经部分升级到 omv7，则上面命令应该不存在（即无法重复执行）。

此时需要使用 script 尝试进行补救：

# copyright: ryecoaaron openmediavault
# ref: https://forum.openmediavault.org/index.php?thread/51247-omv-6-x-to-7-x-upgrade-with-errors-update-packages-search-does-not-work-plugin-l/
head /usr/sbin/omv-mkaptidx
sudo rm /usr/sbin/omv-mkaptidx
wget -O - https://github.com/OpenMediaVault-Plugin-Developers/installScript/raw/master/fix6to7upgrade | sudo bash

问题：WEB UI 登录后显示 502，且 SSH 无法登陆

该问题在于 omv7 使用 php8，而 omv6 使用 php7，而当前虽然已经升级到 omv7，但配置错误为 php7。

上述问题一般也为安装不全导致，如果使用修复脚本不起作用，可以执行一下命令：

omv-salt stage run deploy

该命令会将新的 omv 命令应用到系统，一般执行完成后即可使系统回复正常。

问题：pve-firmware 升级错误，与 firmware-intel-sound 冲突

升级到 omv7 后，再次执行 omv-upgrade，会出现如下报错：

# ...
Preparing to unpack .../pve-firmware_3.15-2_all.deb ...
Unpacking pve-firmware (3.15-2) over (3.14-3) ...
dpkg: error processing archive /var/cache/apt/archives/pve-firmware_3.15-2_all.deb (--unpack):
 trying to overwrite '/lib/firmware/intel/avs/apl/dsp_basefw.bin', which is also in package firmware-intel-sound 20241210-1~bpo12+1
Errors were encountered while processing:
 /var/cache/apt/archives/pve-firmware_3.15-2_all.deb

原因是 Proxmox 的 pve-firmware 中已经包含了 firmware-intel-sound 包，因此产生冲突，删除该包即可：

sudo apt-get purge firmware-intel-sound

详见：“pve-firmware 3.15-2 Update Fails”

其他问题：openmediavault-hddfanctrl 配置后运用不正常

配置 openmediavault-hddfanctrl 插件并选中对应风扇和硬盘并应用后，对应的 Fan 以最小并固定的转速运行， 无法为硬盘正确降温。

原因是升级 omv7 后 hdparm 包不知为何丢失，重新安装即可：

sudo apt-get install hdparm

安装后重启 openmediavault-hddfanctrl 服务即可。

什么是 Flathub

简单理解为在 Linux 中使用 FLatpak 技术，类似 Microsoft Store / Mac App Store / Unbuntu Snap Store 的应用商店。 可以在其官网流浪并安装应用，Flathub 也是一个 repo，也可以通过通用命令安装应用：

APP_ID=<your-app-id>
flatpak install flathub $APP_ID
flatpak run $APP_ID

从哪里开始

由于 Flathub 相对普通的自打包有诸多额外限制， 因此强烈建议从 “For app authors” 开始仔细阅读每一个章节。 本文只从 “Table Habit” 创建于提交流程出发，记录整个过程和踩到的坑。

1. 基本要求

这里是一些基本要求，这里整理了指向官方文档的链接。需要注意的是下面内容只截至到本文发表时间保证有效，如有区别请以 Flathub 官方文档为准：

还有一些构建时的限制：

• 构建时无网络访问，即在 bnuild-options 中使用 --share=network 无效。 由于 Flutter 默认会在构建时自动下载相关依赖，因此使用 Flathub 官方教程在进行构建时几乎一定会失败。 后续会介绍使用 flatpak-flutter 进行预处理，保证可以构建成功。
• 尽量从源码构建。紧接上一条，由于 Flutter 应用依赖外部下载，因此一种解决的方法便是预构建二进制文件， 再由 Flathub 直接分发。但由于不是由 Flathub 构建，可能出于导致各种各样的兼容性问题的原因， Flathub 默认需要从源码构建（私货：个人强烈同意，从源码构建甚至是可重复构建从安全角度对于自由/开源软件是必须的）。 flatpak-flutter 可以避免二进制分发，后面会赘述。

2. 准备 Repo

使用 Github Cli：

gh repo fork --clone flathub/flathub
cd flathub
git checkout --track origin/new-pr
git checkout -b my-app-submission new-pr

或者手动操作：

1. Fork Flathub/Flathub，同时取消勾选 “Copy the master branch only”。

2. 执行以下操作：

   git clone --branch=new-pr git@github.com:<your-github-name>/flathub.git && cd flathub
   git checkout -b my-app-submission new-pr
   

确保当前分支从 new-pr 派生并且命名为 my-app-submission。

3. 需求文件与内容

确保上面创建的本地 repo 中包含以下文件，可选文件请参考 “Required files”：

1. manifest.yml/yaml/json：清单文件必须存在，并以 <app-id>.yml/yaml/json 命名。 如果使用 flatpak-flutter 该文件会由对应的 Manifest 模板自动生成。

还有一些必要的文件 Flathub 几乎是强制要求在上游 repo 中维护。 不过实际查看中很多应用将这些文件放在了该 repo 中，如有需求请在提交后和维护者沟通， 这里（包含后续）默认这些文件存放在上游 repo：

1. metadata.xml：需要通过 Flathub 定制的 appsstream 合法性验证，后续会详细说明。
2. 应用程序图标：要求是 svg 或者 png，后续也会再次说明；对于 GUI 应用是必选的。
3. <app-id>.desktop：该文件对 GUI 应用是必选的。

4. flatpak-flutter

在“1. 基本要求”中，说明了 Flutter 应用默认在离线环境中几乎无法进行构建， 但 Flathub 又需要尽量避免直接提交二进制文件， 因此我们需要在清单文件中列出需要构建的 Flutter 应用中所有依赖 package 的源码构建信息。

上面如果手动操作的话需要查询 pubspec.lock 并手动或写一个脚本生成所有依赖描述， 这无疑是一项大工程，幸好有 flatpak-flutter 这个现成的轮子。

该项目的简单原理就是将 flutter 中所有需要下载的流程转化为 Manifest 中的描述格式， 一般包含：

• flutter-sdk-x.y.z.json：编译 FLutter 需要的依赖
• pubspec-sources.json：pubspec.lock 中列出的依赖

具体说明和更多用法（比如处理外部依赖）可以直接看该项目的 README。

而对于一个简单的 Flutter 项目，我们需要做的是：

1. 创建一个需要的 Manifest 模板文件，一般命名为 flatpak-flutter.yml/yaml
2. 按 [5. Manifest] 中示例编写 Manifest 文件
3. 执行 flatpak-flutter flatpak-flutter.yml
4. 成功后，将生成的额外清单文件加入 repo

建议在 .gitignore 中加入如下内容，这些都是 flathub / flatpak-flutter 运行过程中的中间产物：

.flatpak-builder/
build/
repo/

5. Manifest

与上篇文章中的 “Manifest” 大致相同，但有些许区别。

下面还是先贴上 flathub/io.github.friesi23.mhabit 中使用的清单文件（flatpak-flutter.yaml）：

# yaml-language-server: $schema=https://raw.githubusercontent.com/flatpak/flatpak-builder/main/data/flatpak-manifest.schema.json

---
app-id: io.github.friesi23.mhabit
runtime: org.freedesktop.Sdk
runtime-version: "24.08"
sdk: org.freedesktop.Sdk
sdk-extensions:
  - org.freedesktop.Sdk.Extension.llvm19
command: mhabit
separate-locales: false
finish-args:
  - --share=network
  - --share=ipc
  - --device=dri
  - --socket=fallback-x11
  - --socket=wayland
  - --talk-name=org.freedesktop.Notifications
modules:
  - shared-modules/libsecret/libsecret.json
  - name: jsoncpp
    buildsystem: meson
    config-opts:
      - --buildtype=release
      - --default-library=shared
    sources:
      - type: archive
        url: https://github.com/open-source-parsers/jsoncpp/archive/refs/tags/1.9.6.tar.gz
        sha256: f93b6dd7ce796b13d02c108bc9f79812245a82e577581c4c9aabe57075c90ea2
    cleanup:
      - "/lib/*.a"
      - "/include"
  - name: mhabit
    buildsystem: simple
    build-options:
      arch:
        x86_64:
          env:
            BUNDLE_PATH: build/linux/x64/release/bundle
        aarch64:
          env:
            BUNDLE_PATH: build/linux/arm64/release/bundle
      append-path: /usr/lib/sdk/llvm19/bin:/run/build/mhabit/flutter/bin
      prepend-ld-library-path: /usr/lib/sdk/llvm19/lib
      env:
        PUB_CACHE: /run/build/mhabit/.pub-cache
    build-commands:
      - flutter build linux --release
      - install -D $BUNDLE_PATH/mhabit /app/bin/mhabit
      - install -Dm644 assets/logo/macos.svg /app/share/icons/hicolor/scalable/apps/io.github.friesi23.mhabit.svg
      - install -Dm644 flatpak/io.github.friesi23.mhabit.metainfo.xml -t /app/share/metainfo
      - install -Dm644 flatpak/io.github.friesi23.mhabit.desktop -t /app/share/applications
      - cp -r $BUNDLE_PATH/lib /app/bin/lib
      - cp -r $BUNDLE_PATH/data /app/bin/data
    sources:
      - type: git
        url: https://github.com/FriesI23/mhabit.git
        tag: flathub-v1.16.22+92
        commit: cbedd98a6e24a6a5cc0a48bcea925928ac2087ae
        disable-submodules: true
      - type: git
        url: https://github.com/flutter/flutter.git
        tag: 3.24.5
        dest: flutter

这里列出几个和自己构建不一样的部分：

5.1. runtime

截止该文章撰写时，Flathub 要求使用的 freedesktop 版本是 24.08，其他版本可能会被维护者问询或者拒绝， 如无其他必要请确保使用 Flathub 中支持（建议）使用的 runtime 包和对应版本。

runtime: org.freedesktop.Sdk
runtime-version: "24.08"

5.2. llvm19

编译 Flutter 需要使用 clang，因此需要引入 llvm。 请注意不同 runtime 对应的 llvm 版本，如果不清楚可以使用以下命令查看：

flatpak remote-ls flathub --user | grep org.freedesktop.Sdk.Extension.llvm

sdk-extensions:
  - org.freedesktop.Sdk.Extension.llvm19
# ...
modules:
  - name: mhabit
    build-options:
      # ...
      append-path: /usr/lib/sdk/llvm19/bin:...
      prepend-ld-library-path: /usr/lib/sdk/llvm19/lib
    # ...

5.3. finish-args

权限是个人在提交验证错误的并要求修改的重灾区，因为 Flathub 不光检查清单文件的合法性， 还会有很多额外的限制，具体请看：“Linter”，并搜索以 “finish-args-“ 开头的语法。 个人在实践中主要遇到了一下几个问题：

• finish-args-arbitrary-dbus-access：Fluthub 禁止对任意 dbus 的访问，如有需要请申请具体的 dbus 名称， 一般不需要申请这个。
• finish-args-portal-talk-name：Flatpak 默认允许 --talk-name=org.freedesktop.portal.<...>，无需重复申请。 Flathub 会检查这些权限，如果存在则报错。

还有一些权限需要仔细检查是否需要：

• --talk-name=org.freedesktop.Notifications：如果代码或者依赖包不支持使用 org.freedesktop.portal 接口弹出通知则需要该权限。
• --talk-name=org.freedesktop.<...>：同上，如果代码使用 protal 接口，则都不需要申请权限，反之亦然。

finish-args:
  - --share=network
  - --share=ipc
  - --device=dri
  - --socket=fallback-x11
  - --socket=wayland
  - --talk-name=org.freedesktop.Notifications

5.4. shared-modules

一些 Flathub 中已经定义好的库存放在 flathub/shared-modules 中， 可以通过使用 submodule 引入后直接使用：

git submodule add https://github.com/flathub/shared-modules.git

modules:
  - shared-modules/libsecret/libsecret.json

5.5. flutter

通过以下方式引入 Flutter，由于 flakpak-flutter 脚本限制， 现在 sources 中的 App 和 Flutter 本身都需要使用 git 和 url 的方式引入， 因此如果有特殊需要可以主动修改并提 PR….

modules:
  - name: mhabit
    build-options:
      # ...
      append-path: ...:/run/build/mhabit/flutter/bin
      env:
        PUB_CACHE: /run/build/mhabit/.pub-cache
    # ...
    sources:
      - type: git
        url: https://github.com/FriesI23/mhabit.git
        tag: flathub-v1.16.22+92
        commit: cbedd98a6e24a6a5cc0a48bcea925928ac2087ae
        disable-submodules: true
      - type: git
        url: https://github.com/flutter/flutter.git
        tag: 3.24.5
        dest: flutter

5.6. 其他

• Flathub 现在要求将所有的 modules 都内联（inline），因此如无必要尽量不要手动拆分为多个文件。

• 请务必在文件头引入以下内容保证基本格式符合 flatpak 要求。

  # yaml-language-server: $schema=https://raw.githubusercontent.com/flatpak/flatpak-builder/main/data/flatpak-manifest.schema.json
  ---
  # manifest content
  # ...
  

6. Metainfo 和 Desktop

两者请在上游维护，并在 Manifest 中引用。以自己的应用为例：

在应用仓库维护如下结构：

/root/flatpak
├── io.github.friesi23.mhabit.desktop
├── io.github.friesi23.mhabit.metainfo.xml
└── screenshots
    ├── en-US
    │   ├── 1.png
    │   ├── 2.png
    │   ├── 3.png
    │   ├── 4.png
    │   ├── 5.png
    │   └── 6.png
    └── zh-CN
        ├── 1.png
        ├── 2.png
        ├── 3.png
        ├── 4.png
        ├── 5.png
        └── 6.png

在 Manifest 的 build-commands 中引用：

modules:
  - name: mhabit
    build-commands:
      # 编译二进制文件
      - flutter build linux --release
      # 安装主程序
      - install -D $BUNDLE_PATH/mhabit /app/bin/mhabit
      # 安装图标
      - install -Dm644 assets/logo/macos.svg /app/share/icons/hicolor/scalable/apps/io.github.friesi23.mhabit.svg
      # 安装元信息
      - install -Dm644 flatpak/io.github.friesi23.mhabit.metainfo.xml -t /app/share/metainfo
      # 安装桌面文件
      - install -Dm644 flatpak/io.github.friesi23.mhabit.desktop -t /app/share/applications
      # 安装构建依赖
      - cp -r $BUNDLE_PATH/lib /app/bin/lib
      - cp -r $BUNDLE_PATH/data /app/bin/data
    # ...
    sources:
      - type: git
        url: https://github.com/FriesI23/mhabit.git
        tag: flathub-v1.16.22+92
        commit: cbedd98a6e24a6a5cc0a48bcea925928ac2087ae
        disable-submodules: true
      - type: git
        url: https://github.com/flutter/flutter.git
        tag: 3.24.5
        dest: flutter

另外自己在实践中有几点需要注意：

1. 必须包含至少一个截图，并描述在 screenshots/screenshot 节点中。
2. releases 节点必须包含且至少含有一个版本，且不要随意删除版本，否则可能出发 Flathub 审查。

有关元信息相关可以查看官方文档：“Appstream Validation Errors”

与其他应用商店类似，Falthub 也存在一个质量文档，可以查看 “Quality guidelines” 并遵嘱其中标准以获得更好的产品体验。

7. 准备本地构建

此时先保证已经执行了 flatpak-flutter flatpak-flutter.yml，此时本地 repo 结构应如下：

├── .git
├── .gitignore
├── .gitmodules                     # submodule 描述信息，如果引入类似 shared-modules 则需要
├── flatpak-flutter.yml # 模板文件
├── flutter-sdk-3.24.5.json         # 注：这里是你自己配置的 Flutter 版本
├── flutter-shared.sh.patch         # Patch 文件也要包含在内
├── io.github.friesi23.mhabit.yml   # 生成的 Manifest 文件
├── package_config.json
├── pubspec-sources.json            # 第三方 package 的 Manifest 文件
└── shared-modules                  # 如果没有拉取 submodule，则使用 git submodule update --init --recursive 获取

# 检查 Manifest 文件是否符合 Flathub 要求
# 如果执行后有报错则一定要处理，否则后续提 PR 的测试构建 CI 必然会失败
# 理想情况什么都不会输出
# flatpak run --command=flatpak-builder-lint org.flatpak.Builder \
#   manifest your-app-id.yml
flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest \
  io.github.friesi23.mhabit.yml

# 检查 Metainfo 文件是否符合 Flathub 要求
# 具体同上，先保证这两个验证可以通过
# flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream \
#   your-app-id.yml.metainfo.xml
flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream \
  io.github.friesi23.mhabit.metainfo.xml

# 使用和 Flathub 相同的环境进行构建，如果失败可以尝试时候下面给出的命令尝试构建：
# flatpak-builder --repo=repo --force-clean --sandbox --user \
#   --install --install-deps-from=flathub build your-app-id.yml
# 如果上面命令成功，则可能是环境问题
# e.g. 不要在 vscode 的内建 shell 内执行，建议使用标准的 Terminal
#      或者一个干净的 shell 环境，然后重复下面的 Flathub 构建命令。
#
# flatpak run --command=flathub-build org.flatpak.Builder your-app-id.yml
flatpak run --command=flathub-build org.flatpak.Builder \
  io.github.friesi23.mhabit.yml

# 对构建产物（repo）再进行一次检查
# 具体同上述检查流程，保证没有报错，尽量没有警告
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo

8. 准备提交

这里引用原文：

Now open a pull request against the new-pr base branch on GitHub. The title of the PR should be “Add org.example.MyAwesomeApp”.

如图：

然后就是按 Review 结构进行修改，最后等待通过即可。

9. Done

通过后，该 PR 会被自动关闭，同时新生成一个 Flathub/<your.app.id> 的仓库，并会收到一个邀请，接收后即可自行维护， 这也代表该 App 已被 Flathub 接收，稍后便能在 flathub.org 中查询到。

后需维护请参考：“App Maintenance”。

总结

由于事先以自行查阅大量文档和其他应用的 repo 且已经成功构建出 Flatpak Single-file Bundle， 也因为 App 本省体量较小，因此提交时并没有遇到很多问题。

其中比较容易踩坑的就是权限问题，因为申请的权限即使用不到测试时也不会报错，而做减法永远是有风险的， 因此浪费了一定的时间排查。

应用上架的 PR 可以查看：“Add io.github.friesi23.mhabit #6732”

当然也建议查看其他 Open 或者 Closed 的 PR，参考学习别人的提交流程 （当然超过一两年没更新的应用就算了，可能不符合 Flathub 的最新标准），可以为极大加速应用被合并时间。

最后附赠一些可能有用的链接：

• Flathub - Requirements
• Flathub - Submission
• Flathub - Maintenance
• Flathub - Flatpak builder lint
• Flathub - MetaInfo guidelines
• Flatpak - Manifest
• Flatpak - Sandbox Permissions
• Flatpak - Module Sources
• AppStream - MetaInfo Creator
• Debian - appstreamcli

准备大体上拆分为两个部分：如何打包自己的 .Flatpak Bundle 与上架 Flathub 的正确姿势。本文将介绍上半部分, 如想直接查看 Flathub 上架流程请移步： 为 Flutter 应用打包为 Flatpak 并以正确的姿势上架到 Flathub (下)。

什么是 Flatpak

这里不加自己的理解，直接贴上 wiki 的原文：

Flatpak is a utility for software deployment and package management for Linux. It provides a sandbox environment in which users can run application software in (partial) isolation from the rest of the system.

“Flatpak History “ 也可以了解到其简要时间线。

将自己的 Flutter 应用打包为可安装的 Flatpak 单文件包（Single-file Bundle）

不论怎样，我都希望能够在应用每个版本发布后的 Release 界面中能够为使用者提供可供下载和安装的二进制文件， 因此需要在自动构建 CI 上增加对 Flatpak 单文件包的支持。当然还是以我自己的应用（Table Habit）为例：

1. 创建必要文件
2. 构建产物
3. 自动化

1. 创建必要文件

对于 GUI 应用，我们在正式打包前需要创建一些必要的元信息来让 Flatpak 知道怎样进行打包， 大致包含以下几个文件：

• <manifest>.yaml/yml/json：清单文件，Flakpak 需要。
• <metainfo>.xml：元信息，对应的桌面服务（e.g. Xfce）需要，Flakpak 也会读取里面相关信息。
• <metainfo>.desktop：桌面文件，对应的桌面服务（e.g. Xfce）需要。

1.1. 初始化

具体步骤请参考：“Building your first Flatpak”。 简而言之，已 Debian/Xfce 为例，执行如下命令进行初始化：

# refs: https://flatpak.org/setup/Debian
sudo apt install flatpak flatpak-builder
sudo apt install gnome-software-plugin-flatpak
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
# rebbot

1.2. Manifests

首先我们需要一个 Manifest （清单）文件，Flatpak 使用 Manifest 文件进行构建， 该文件会提供有关应用程序的基本信息和构建说明。

Flatpak 的文档很详细，可以在 “Manifests” 中找到每个 key 值的定义。 我的清单文件如下（这是一个典型的自构建 flutter 清单，请与后续提交到 Flathub 的清单进行区分）， 里面部分配置会进行注释说明：

app-id: io.github.friesi23.mhabit
runtime: org.freedesktop.Sdk
runtime-version: "23.08"
sdk: org.freedesktop.Sdk
command: mhabit
separate-locales: false
finish-args:
  - --share=network
  - --share=ipc
  - --socket=fallback-x11
  - --socket=wayland
  - --device=dri
  - --talk-name=org.freedesktop.portal.Desktop
  - --talk-name=org.freedesktop.Notifications
modules:
  # Required by: flutter_secure_storage
  # https://github.com/flathub/shared-modules/blob/master/libsecret/libsecret.json
  - name: libsecret
    buildsystem: meson
    config-opts:
      - -Dmanpage=false
      - -Dvapi=false
      - -Dgtk_doc=false
      - -Dintrospection=false
    cleanup:
      - /bin
      - /include
      - /lib/pkgconfig
      - /share/man
    sources:
      - type: archive
        url: https://download.gnome.org/sources/libsecret/0.21/libsecret-0.21.6.tar.xz
        sha256: 747b8c175be108c880d3adfb9c3537ea66e520e4ad2dccf5dce58003aeeca090

  - name: jsoncpp
    buildsystem: meson
    config-opts:
      - --buildtype=release
      - --default-library=shared
    sources:
      - type: archive
        url: https://github.com/open-source-parsers/jsoncpp/archive/refs/tags/1.9.6.tar.gz
        sha256: f93b6dd7ce796b13d02c108bc9f79812245a82e577581c4c9aabe57075c90ea2

  - name: mhabit
    buildsystem: simple
    build-options:
      arch:
        x86_64:
          env:
            BUNDLE_PATH: build/linux/x64/release/bundle
        aarch64:
          env:
            BUNDLE_PATH: build/linux/arm64/release/bundle
    build-commands:
      - install -D $BUNDLE_PATH/mhabit /app/bin/mhabit
      - install -Dm644 assets/logo/macos.svg /app/share/icons/hicolor/scalable/apps/io.github.friesi23.mhabit.svg
      - install -Dm644 configs/flatpak_builder/io.github.friesi23.mhabit.metainfo.xml -t /app/share/metainfo
      - install -Dm644 configs/flatpak_builder/io.github.friesi23.mhabit.desktop -t /app/share/applications
      - cp -r $BUNDLE_PATH/lib /app/bin/lib
      - cp -r $BUNDLE_PATH/data /app/bin/data
    sources:
      - type: dir
        path: ../../

1.2.1. app-id

也可以使用 id, app-id 是应用的唯一标识，应该与自己构建应用本身的 bundle 保持一致。 该 id 显示如下， 最后启动应用（执行 flatpak run <your-app-id>）时也使用的是该 id。

$flatpak list --app
Name                             Application ID                    Version            Branch         Installation
Table Habit                      io.github.friesi23.mhabit         1.16.22+92         stable         user
Flatpak Builder Flatpak          org.flatpak.Builder               v0-Flathub         stable         user
...

1.2.2. runtime, runtime-version && sdk

指名该应用需要的运行时环境，指名后应用安装时（flatpak install ...）会自动提示所有依赖的 package 依赖并安装（ 如果使用 -y 则会自动安装）。

使用 flatpak remote-ls flathub --runtime --user 可以查看 Flathub 中可支持的所有 runtime。 不知道用哪个就遵循如下：

• GTK: org.gnome.Platform
• KDE/Qt: org.kde.Platform
• 跨桌面: org.freedesktop.Platform
  • 兼容版本：23.08
  • * Flathub 要求的版本：24.08

选择 runtime 后可以选择对应的 sdk，已 freedesktop 为例，使用 org.freedesktop.Sdk

1.2.3. command

填写程序入口的文件名，flutter 应用的入口就是打包后位于 build/linux/<arch>/release/bundle/<pubspec.yaml#name>

1.2.4. finish-args

声明应用所需要的权限，请仔细阅读并参考 “Sandbox Permissions”。 下面只列举个人使用的部分权限：

• --share=network：如果应用需要访问网络，则加上这个权限。
• --socket=wayland && --socket=fallback-x11：对于 GUI 程序，这两个一起使用。
• --device=dri：启用图形加速支持，一般都加上。
• --talk-name=org.freedesktop.portal.Desktop：portal 权限，用于 freedesktop 与图形系统接口通信。
  • 注意：flathub 上架的应用默认包含这个权限，所以不用添加
• --talk-name=org.freedesktop.Notifications：flutter_local_notification 需要这个权限进行通知消息弹出。
  • 注意：如果代码使用 freedesktop.protal 进行通知通信，则不需要声明这个权限，对于其他 --talk-name=... 都适用。
    • e.g. libsecret1 支持 freedesktop.protal 通信，因此不需要声明 --talk-name=org.freedesktop.secrets 权限。

注：对于上架 Flathub 的应用，权限申请有一些额外规范，请参考 “Flatpak builder lint”。

1.2.5. modules

声明需要打包的模块，所有可配置字段参阅文档：“Module Sources”。

一般配置本体应用打包即可，如果有额外模块，请参考文档进行源码引入并声明编译流程。一般参考配置方法的两个途径：

1. flathub/shared-modules
2. 以 jsoncapp 为例（对应 apt-get install libjsoncpp-dev）：https://github.com/search?q=org:flathub jsoncpp&type=code

一个需要注意的点是：所有 path 字段如果配置相对路径，路径起点都是 Manifest 文件所在位置。

抄一个好的配置文件是学习的开端，个人推荐：flathub/com.visualstudio.code

1.3. Metainfo

Appstream 定义了 metainfo，旨在为软件在跨平台提供统一的元数据。Flatpak 中也建议使用 metainfo.xml， 可以参考 “MetaInfo files” 章节获得相关信息。

注：Flathub 对 GUI 应用的 metainfo 是强制要求，并且有额外的 lint 检查， 请注意并参考 “Flatpak builder lint”。

举个栗子：appstream-missing-screenshots 要求商家 flathub 的应用必须提供至少一个截图。

下面也贴出自己应用使用的元信息：

<?xml version="1.0" encoding="utf-8"?>
<component type="desktop">
  <id>io.github.friesi23.mhabit</id>
  <name>Table Habit</name>
  <summary>Micro habit tracker for personal growth</summary>
  <metadata_license>MIT</metadata_license>
  <project_license>Apache-2.0</project_license>
  <developer_name>Fries_I23</developer_name>
  <launchable type="desktop-id">io.github.friesi23.mhabit.desktop</launchable>
  <provides>
    <binary>mhabit</binary>
  </provides>
  <screenshots>
    <screenshot type="default">
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/1.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/1.png</image>
      <caption>Home screen</caption>
      <caption xml:lang="zh-CN">主界面</caption>
    </screenshot>
    <screenshot>
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/2.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/2.png</image>
      <caption>Dark mode</caption>
      <caption xml:lang="zh-CN">深色模式</caption>
    </screenshot>
    <screenshot>
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/3.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/3.png</image>
      <caption>Expanded habit list</caption>
      <caption xml:lang="zh-CN">展开习惯列表</caption>
    </screenshot>
    <screenshot>
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/4.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/4.png</image>
      <caption>Habit detail screen</caption>
      <caption xml:lang="zh-CN">习惯详细信息界面</caption>
    </screenshot>
    <screenshot>
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/5.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/5.png</image>
      <caption>Habit heatmap</caption>
      <caption xml:lang="zh-CN">习惯热力图</caption>
    </screenshot>
    <screenshot>
      <image>
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/en-US/6.png</image>
      <image xml:lang="zh-CN">
        https://raw.githubusercontent.com/FriesI23/mhabit/57cd99697b852b69f6ce9e954aa7827db62ca085/flatpak/screenshots/zh-CN/6.png</image>
      <caption>Batch editing screen</caption>
      <caption xml:lang="zh-CN">批量修改界面</caption>
    </screenshot>
  </screenshots>
  <description>
    <p>"Table Habit" is an app that helps you establish and track your own micro habit.
      It includes a complete set of growth curves and charts to help you build habits more
      effectively,
      and keeps your data in sync across devices (currently via WebDAV, with more options coming
      soon).</p>
    <p>Moreover, this app is completely open source and comes with these features:</p>
    <ul>
      <li>A scoring system to help develop your own micro habits.</li>
      <li>Support both positive and negative habit.</li>
      <li>An easy-to-use interface for habit check in.</li>
      <li>Different colors used to distinguish between various habits.</li>
      <li>Easily export and import habits using a human-readable format (JSON).</li>
      <li>Adapt to Material3 and Dynamic Color for Android 12 and later versions.</li>
      <li>Adaptation for landscape and large screen devices.</li>
      <li>[Experimental] Support network sync with WebDAV.</li>
      <li>No ADs in this app.</li>
    </ul>
  </description>
  <url type="vcs-browser">https://github.com/FriesI23/mhabit</url>
  <url type="bugtracker">https://github.com/FriesI23/mhabit/issues</url>
  <url type="homepage">https://github.com/FriesI23/mhabit</url>
  <url type="donation">https://github.com/FriesI23/mhabit?tab=readme-ov-file#donate</url>
  <url type="translate">https://hosted.weblate.org/engage/mhabit/</url>
  <url type="contribute">https://github.com/FriesI23/mhabit?tab=readme-ov-file#contributing</url>
  <!-- Auto generate by: https://hughsie.github.io/oars/generate.html -->
  <content_rating type="oars-1.1"/>
  <!-- https://specifications.freedesktop.org/menu-spec/latest/category-registry.html -->
  <categories>
    <category>Utility</category>
  </categories>
  <releases>
    <release version="1.16.22+92" date="2025-07-17">
      <url type="details">https://github.com/FriesI23/mhabit/releases/tag/flathub-v1.16.22+92</url>
    </release>
    <release version="1.16.22+91" date="2025-07-16">
      <url type="details">https://github.com/FriesI23/mhabit/releases/tag/v1.16.22+91</url>
    </release>
    <release version="1.16.21+90-pre" date="2025-07-15">
      <url type="details">https://github.com/FriesI23/mhabit/blob/main/CHANGELOG.md</url>
    </release>
  </releases>
</component>

其中有几个需要注意：

1. <component type="desktop"> 对于 GUI 应用是必须且是 rootNode。
2. id 标签请与 manifest 中保持一致。
3. <launchable type="desktop-id"> 配置了桌面（Xfce 等）的启动信息， 如果想要应用能够从桌面菜单通过鼠标点击启动，这个配置是必须的。.desktop 文件下个章节会提到。
4. content_rating 标签建议自动生成，网址代码中已提及。
5. categories 请使用 Freedesktop 支持的标签名，不然 linter 检查会报错，合法标签信息网址也在代码中标注。
6. releases 信息需要手动维护，flatpak 在显示应用是会自动使用 date 最后的一个， 可以写一个脚本进行维护（e.g. scripts/gen_flatpak_info.sh）。 当然如果有更好的方案也可以进行分享，终归是不想也不喜欢重复造轮子。

最后通过一下命令检查 <metainfo>.xml 是否合法：

appstreamcli validate --pedantic /path/to/metainfo.xml

1.4. Desktop

Desktop 文件用于向桌面环境提供有关应用的信息，可以手动创建，也可以由 appstream 介由 metainfo.xml 文件生成。

appstreamcli make-desktop-file <app-id>.xml <app-id>.desktop

Desktop 文件比较简单，如下：

[Desktop Entry]
Name=Table Habit
Comment=Micro habit tracker for personal growth
Exec=mhabit
Icon=io.github.friesi23.mhabit
Terminal=false
Type=Application
Categories=Utility
StartupNotify=true

相关文档也可在 “Desktop files” 章节中找到。

2. 构建产物

目标是构建 Flatpak 单文件包，因此 repo 只作为构造中间产物出现，如果需要已 repo 的形式构建并安装， 请参考：“Flatpak/Publishing”.

# 安装依赖
apt-get install -y flatpak flatpak-builder
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
# 根据 <manifest>.yaml 内的 runtime 获取对应的构建依赖，这里以 freedesktop-23.08 举例
flatpak install -y org.freedesktop.Sdk/x86_64/23.08
flatpak install -y org.freedesktop.Platform/x86_64/23.08
flatpak install -y flathub org.freedesktop.appstream-glib
# 构建 linux 产物
flutter build linux --release
# 构建 flatpak repo
flatpak-builder --force-clean build-dir \
    --repo=repo-dir --default-branch=main \
    <path/to/manifest.yaml>
# 构建 flatpak bundle
flatpak build-bundle repo-dir <custom-name>.flatpak <app-id> main

3. 自动化

将上面的步骤集成到 Github Action 中，每次推送对应 tag 都能自动进行 Release 版本构建并发布。

由于第三方 Workflow flatpak/flatpak-github-actions/flatpak-builder@v6 需要使用自定义容器， 因此将构造 Linux 产物和构造 Flatpak 产物分为两个 job 执行，并使用 artifact 传递构造中间产物。

name: Release
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+\+[0-9]+'

jobs:
  # Step1: 编译 Linux 二进制文件
  build-linux:
    name: "Build Linux Bundle"
    strategy:
      # symbol `g_once_init_enter_pointer`` was introduced in glib>=2.80,
      # fallback build host to ubuntu-22.04 for better compatibility.
      # refs: https://github.com/cirruslabs/docker-images-flutter/issues/337.
      matrix:
        variant:
          - arch: x86_64
            runner: ubuntu-22.04
            bundle_path: build/linux/x64/release/bundle
          - arch: aarch64
            runner: ubuntu-22.04-arm
            bundle_path: build/linux/arm64/release/bundle
    runs-on: ${{ matrix.variant.runner }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Init Flutter
        uses: ...
      - name: Build Linux Bundle
        env:
          BUNDLE_PATH: ${{ matrix.variant.bundle_path }}
        run: flutter build linux --release
      - name: Upload Bundle
        uses: actions/upload-artifact@v4
        with:
          name: linux-bundle-${{ matrix.variant.arch }}
          path: ${{ matrix.variant.bundle_path }}
          if-no-files-found: error
          retention-days: 1

  # Step2: 打包为 Flatpak Bundle
  build-linux-flatpak:
    name: "Build Flatpak Bundle"
    needs:
      - build-linux
    container:
      # https://github.com/flathub-infra/actions-images/pkgs/container/flatpak-github-actions
      # 根据对应 runtime 选择
      image: ghcr.io/flathub-infra/flatpak-github-actions:freedesktop-23.08
      options: --privileged
    strategy:
      matrix:
        variant:
          - arch: x86_64
            runner: ubuntu-22.04
            bundle_path: build/linux/x64/release/bundle
          - arch: aarch64
            runner: ubuntu-22.04-arm
            bundle_path: build/linux/arm64/release/bundle
    runs-on: ${{ matrix.variant.runner }}
    env:
      ARTIFACT_NAME: linux-bundle-${{ matrix.variant.arch }}
      FLATPAK_BUNDLE: output-${{ matrix.variant.arch }}.flatpak
    steps:
      - uses: actions/checkout@v4
      - name: Fetch Bundle
        id: fetch-bundle-step
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.ARTIFACT_NAME }}
          path: ${{ matrix.variant.bundle_path }}
          # 填写一个可用的 Github Token，否则可能找到 API 限制
          # github-token: ${{ secrets.APP_RELEASE_TOKEN }}
      - name: Build .flatpak
        uses: flatpak/flatpak-github-actions/flatpak-builder@v6
        with:
          bundle: ${{ env.FLATPAK_BUNDLE }}
          manifest-path: /path/to/manifest.yml
          arch: ${{ matrix.variant.arch }}
          # branch: main
          upload-artifact: false
      - name: Release
        uses: ncipollo/release-action@v1
        with:
          allowUpdates: true
          omitBodyDuringUpdate: true
          omitDraftDuringUpdate: true
          omitPrereleaseDuringUpdate: true
          artifacts: >
            ${{ env.FLATPAK_BUNDLE }}
          # 填写一个可用的 Github Token，否则可能找到 API 限制
          # token: ${{ secrets.APP_RELEASE_TOKEN }}

结语

以上，便能构造一个 output.flatpak 文件， 如果一切正常的话可以通过 flatpak install --user output.flatpak 进行安装验证。

下一篇文章会介绍如何以正确的姿势发布到 Flathub，由于 Flathub 自身有一些特殊发布规则，因此流程也会不太一样。 不过 Flathub 建议由上游自行维护 metainfo.xml 文件， 因此建议从一开始就保持自己发布的 metainfo.xml 与 Flathub 要求兼容，具体 lint 检查放在下篇文章中。

• 为 Flutter 应用打包为 Flatpak 并以正确的姿势上架到 Flathub (下)

而在 Xcode 13 及更高版本中，xcodebuild 可以使用 App Store Connect API 在 Apple Developer 上进行身份验证。 因此我们可以使用该验证方式在 CI 中对代码进行自动签名。

需要准备

1. 一个 Apple 开发者账号。
2. 一个 App Store Connect API 对应的团队密钥（导出为 P8 文件）。
   • Issuer ID
   • API Key
   • API Certificate (Auth_xxx.p8)
3. 一个 Developer Id Application Certificate（导出为 P12 文件）。
   • Certificate (***.p12)
   • Certificate Password

App Store Connect API 团队密钥

访问 App Store Connect / 用户和访问 / App Store Connect API， 选择 团队密钥，然后添加一个新的密钥，完成后下载 p8 证书。

此时我们拥有以下三个需要的信息：

1. Issuer ID: 可以从“团队密钥”下找到。
2. API Key: 可以从“团队密钥 / 有效”下找到（中文名：密钥 ID）。
3. API Certificate：上面下载的文件，由于只能下载一次，请妥善保存。

Developer Id Application Certificate

一个快捷的生成方式：直接在 Xcode 中进行生成。

1. 导航到 Xcode --> Settings... --> Accounts --> Manage Certificates...。
2. 点击左下角 +，点击 Develop ID Application，等待创建完成。
3. 找到刚刚创建的 Certificate，右键单击，选取 Export Certificate。
4. 导出时需要密码，随机生成一个即可，记得记录这个密码，最后会生成一个 p12 文件。

此时我们拥有以下两个需要的信息：

1. Certificate: 刚刚导出的 p12 文件。
2. Certificate Password: 导出时输入的密码。

Github Action Secret Keys

将上面的信息存储到 Repository secrets 中，其中两个文件使用 base64 进行编码。

base64 -i ${your-api-auth}.p8 | pbcopy
base64 -i ${your-certificate}.p12 | pbcopy

同时我们需要一个 APPLE_KEYCHAIN_PASSWORD，后续导入证书时需要使用，随机生成一个字符串填入即可。

Github Action 流程

导入证书

使用以下步骤进行证书导入，这里和 Github 官方文档的区别在于：我们不需要导入配置文件（Provision Profile）。

jobs/<build-app>/steps:
  - name: Import Certificate
    env:
      KEYCHAIN_PASSWORD: $
    run: |
      # create variables
      CERTIFICATE_PATH=$RUNNER_TEMP/certificate.p12
      KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
      # import certificate from secrets
      echo "$" | base64 --decode > $CERTIFICATE_PATH
      # create temporary keychain
      security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
      security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
      security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
      # import certificate to keychain
      security import $CERTIFICATE_PATH \
        -k $KEYCHAIN_PATH \
        -P "$" \
        -A -t cert -f pkcs12
      security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
      security list-keychain -d user -s $KEYCHAIN_PATH

导入 API Key

由于使用配置文件，我们需要使用 “App Store Connect API”，因此需要导入 p8 文件：

jobs/<build-app>/steps:
  - name: Extract App Store Connect API Key
    env:
      APPLE_API_KEY_ID: $
      APPLE_API_AUTHKEY_P8_BASE64: $
    run: |
      mkdir ./private_keys
      echo -n "$APPLE_API_AUTHKEY_P8_BASE64" | base64 --decode --output ./private_keys/AuthKey_$APPLE_API_KEY_ID.p8

手动构建

由于我们需要手动签名，因此不能直接使用 flutter build macos --release 进行构建（会报“找不到配置文件”的错误）。 此时我们需要手动运行构建命名，如下：

由于后续签名需要，这里直接导出归档文件。

jobs/<build-app>/steps:
  - name: Build APP
    env:
      APPLE_TEAM_ID: $
    run: |
      flutter build macos --release --config-only
      xcodebuild CODE_SIGNING_ALLOWED=NO \
        -workspace macos/Runner.xcworkspace \
        -scheme Runner \
        -configuration Release \
        -archivePath build/macos/Runner.xcarchive \
        archive
      # ls -al build/macos/Runner.xcarchive/Products/Applications

签名应用

签名导出时需要使用 xcodebuild -exportArchive 命名，此时需要手动创建一个 ExportOptions.plist 文件。 该文件的具体格式可 GUI 创建方法参考官方文档，这里只给出一个示例：

注意 plist 本身并不支持诸如 <string>${APPLE_TEAM_ID}</string> 之类的格式，这里是作为一个 template， 由 envsubst 进行变量替换生成真正的 plist 文件。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>manageAppVersionAndBuildNumber</key>
    <false/>
    <key>method</key>
    <string>developer-id</string>
    <key>teamID</key>
    <string>${APPLE_TEAM_ID}</string>
  </dict>
</plist>

这里注意需要使用 developer-id，该方法依赖 Developer Id Application Certificate，而我们在上面已经进行导入， 参考“导入证书”。

我们假定将该文件存放在 ./installers/macos_exporter/GithubExportOptions.plist，构建以下步骤：

jobs/<build-app>/steps:
  - name: Signed APP
    env:
      APPLE_API_ISSUER_ID: $
      APPLE_API_KEY_ID: $
      APPLE_TEAM_ID: $
    run: |
      envsubst \
        < ./installers/macos_exporter/GithubExportOptions.plist \
        > ./installers/macos_exporter/GithubExportOptions.resolved.plist
      cat ./installers/macos_exporter/GithubExportOptions.resolved.plist
      plutil -lint ./installers/macos_exporter/GithubExportOptions.resolved.plist
      xcodebuild -exportArchive -archivePath ./build/macos/Runner.xcarchive \
        -exportPath ./build/macos/Build/Products/Release \
        -exportOptionsPlist ./installers/macos_exporter/GithubExportOptions.resolved.plist \
        -allowProvisioningUpdates \
        -authenticationKeyIssuerID $APPLE_API_ISSUER_ID \
        -authenticationKeyID $APPLE_API_KEY_ID \
        -authenticationKeyPath `pwd`/private_keys/AuthKey_$APPLE_API_KEY_ID.p8

最终我们将签名的应用导出到 ./build/macos/Build/Products/Release。

整体流程

这里直接粘贴自己项目中的流程，仅供参考：

Workflow Source

jobs:
  # other actions
  build-macos-dmg:
    name: "Build macos DMG"
    runs-on: macos-latest
    steps:
      - uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: ^16
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup_flutter
      - name: Import Certificate
        env:
          KEYCHAIN_PASSWORD: $
        run: |
          # refs: https://docs.github.com/en/actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development
          # create variables
          CERTIFICATE_PATH=$RUNNER_TEMP/certificate.p12
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
          # import certificate from secrets
          echo "$" | base64 --decode > $CERTIFICATE_PATH
          # create temporary keychain
          security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
          security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
          # import certificate to keychain
          security import $CERTIFICATE_PATH \
            -k $KEYCHAIN_PATH \
            -P "$" \
            -A -t cert -f pkcs12
          security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
          security list-keychain -d user -s $KEYCHAIN_PATH
      - name: Extract App Store Connect API Key
        env:
          APPLE_API_KEY_ID: $
          APPLE_API_AUTHKEY_P8_BASE64: $
        run: |
          mkdir ./private_keys
          echo -n "$APPLE_API_AUTHKEY_P8_BASE64" | base64 --decode --output ./private_keys/AuthKey_$APPLE_API_KEY_ID.p8
      - name: Build APP
        env:
          APPLE_TEAM_ID: $
        run: |
          flutter build macos --release --config-only
          xcodebuild CODE_SIGNING_ALLOWED=NO \
            -workspace macos/Runner.xcworkspace \
            -scheme Runner \
            -configuration Release \
            -archivePath build/macos/Runner.xcarchive \
            archive
          ls -al build/macos/Runner.xcarchive/Products/Applications
      - name: Signed APP
        env:
          APPLE_API_ISSUER_ID: $
          APPLE_API_KEY_ID: $
          APPLE_TEAM_ID: $
        run: |
          envsubst \
            < ./installers/macos_exporter/GithubExportOptions.plist \
            > ./installers/macos_exporter/GithubExportOptions.resolved.plist
          cat ./installers/macos_exporter/GithubExportOptions.resolved.plist
          plutil -lint ./installers/macos_exporter/GithubExportOptions.resolved.plist
          xcodebuild -exportArchive -archivePath ./build/macos/Runner.xcarchive \
            -exportPath ./build/macos/Build/Products/Release \
            -exportOptionsPlist ./installers/macos_exporter/GithubExportOptions.resolved.plist \
            -allowProvisioningUpdates \
            -authenticationKeyIssuerID $APPLE_API_ISSUER_ID \
            -authenticationKeyID $APPLE_API_KEY_ID \
            -authenticationKeyPath `pwd`/private_keys/AuthKey_$APPLE_API_KEY_ID.p8
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          token: $
      - run: npm install -g appdmg
      - name: Build DMP
        run: appdmg ./installers/dmg_creator/config.json ./build/macos/Build/Products/Release/mhabit.dmg
      - name: Released - MacOS
        uses: ncipollo/release-action@v1
        with:
          allowUpdates: true
          omitBodyDuringUpdate: true
          omitDraftDuringUpdate: true
          omitPrereleaseDuringUpdate: true
          artifacts: >
            build/macos/Build/Products/Release/mhabit.dmg
          token: $

问题：应用签名时出现 Segmentation fault: 11

参考该 ISSUE：FB13797668: xcodebuild crashes systematically when exporting an archive (segfault)

该问题已在 Xcode 16 Beta 4 进行修复。如果出现该问题，请指定执行时的 Xcode 版本（而不是使用容器自带的版本）：

jobs/...:
  # https://github.com/maxim-lobanov/setup-xcode
  - uses: maxim-lobanov/setup-xcode@v1
    with:
      xcode-version: ^16  #

参考资料

1. GitHub Actions で Automatically manage signing を使って Flutter の ipa ビルドする
2. Distributing your app for beta testing and releases