给 Flutter 插件加上 Swift Package Manager 支持

欢迎关注微信公众号：FSA全栈行动 👋

一、背景

chat_bottom_container 这个插件我发布也有段时间了，iOS 端一直只配了 CocoaPods，走的是「预编译 xcframework + podspec 里 prepare_command 去 GitHub Releases 下载」的方案，直到最近有人提了一个支持 Swift Package Manager（后面我都简称 SPM） 的 issue：chat_bottom_container#39

了解完发现，从 Flutter 3.44 起， SPM 默认就是开着的，而我这插件只有 podspec、没有 Package.swift，纯 SPM 的工程自然就找不到它。3.44 前后的默认行为正好反过来：

Flutter 版本	SPM 默认状态	手动开关
< 3.44	关闭（opt-in）	得手动执行 flutter config --enable-swift-package-manager 才开
3.44+	默认开启	反过来，想关得设 enable-swift-package-manager: false（具体见文末）

顺带一提，CocoaPods 官方仓库会从 2026-12-02 起转为只读、进入维护模式，SPM 是明摆着的未来，插件迟早都得补上。

那就补上吧，不过动手之前，需要考虑兼容问题，让使用新版本的开发者能顺利用上 SPM，使用 CocoaPods 的开发者也不会被影响。 下面就是我这次从头到尾的过程，以及中间踩到的几个点。最终改动都在这个 PR 里：#40。

二、实战

1、是否删除 podspec ？

加 SPM，要不要顺手把 podspec 换掉？结论是不能删，保留才是官方推荐的做法。原因有几点：

• 不是所有人都在 3.44+。3.44 之前 SPM 得手动 flutter config --enable-swift-package-manager 才开；就算升到 3.44+ 默认开了，用户也能主动关掉（enable-swift-package-manager: false）。这些还走 CocoaPods 的项目，一旦删了 podspec 就直接构建失败。
• Flutter 本身是「二选一回退」的机制：项目开了 SPM、插件又有 Package.swift，就走 SPM；否则老老实实回退到 podspec。两个文件搁一起，工具自己会挑，根本不打架。
• 翻了下官方插件（path_provider_foundation、shared_preferences_foundation 这些），人家也全是 Package.swift 和 podspec 并存的。

所以思路很清晰：加 SPM 是「新增」一个 Package.swift，让它和 podspec 编译同一份源码、依赖同一个 xcframework，而不是二选一。 除非彻底抛弃 CocoaPods，否则不该删它，不然对一个已经发出去的公开插件来说，那是实打实的 breaking change。

2、挪源码位置

SPM 对目录结构有硬性要求，target 的源码默认得放在 Sources/<target 名>/ 底下，而原来的 Swift 文件在 ios/Classes/ 里，位置对不上，先搬过来：

ios/
├── chat_bottom_container/
│   ├── Package.swift                          👈 新增
│   └── Sources/
│       └── chat_bottom_container/
│           ├── ChatBottomContainerPlugin.swift              👈 从 Classes/ 挪过来
│           └── FSAChatBottomContainerGeneratedApis.g.swift  👈 pigeon 生成物
├── Frameworks/
│   └── FSAChatBottomContainer.xcframework
└── chat_bottom_container.podspec

源码一挪走，podspec 里的 source_files 还指着老地址，不改的话 CocoaPods 侧会找不到文件，跟着改到新位置：

# 改前
- s.source_files = 'Classes/**/*'
# 改后
+ s.source_files = 'chat_bottom_container/Sources/chat_bottom_container/**/*.swift'

3、pigeon 的 swiftOut

上面那个 FSAChatBottomContainerGeneratedApis.g.swift 是 pigeon 生成的，输出路径写死在 pigeons/bottom_container.dart 里。文件挪走后，要是哪天重新跑一次 pigeon，它又会照着老路径生成一份，多出个孤儿文件。这种雷当下不改没事，等忘得差不多了它才炸，所以一起改掉：

// 改前
- swiftOut: 'ios/Classes/FSAChatBottomContainerGeneratedApis.g.swift',
// 改后
+ swiftOut: 'ios/chat_bottom_container/Sources/chat_bottom_container/FSAChatBottomContainerGeneratedApis.g.swift',

4、写 Package.swift

这一步才是核心。Package.swift 长这样：

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "chat_bottom_container",
    platforms: [
        .iOS("13.0"),
    ],
    products: [
        .library(name: "chat-bottom-container", targets: ["chat_bottom_container"]),
    ],
    dependencies: [
        // 由 Flutter 工具在构建期提供（Flutter 3.44+），
        // 让插件 target 能访问到 `Flutter` 模块。
        .package(name: "FlutterFramework", path: "../FlutterFramework"),
    ],
    targets: [
        // 预编译的原生实现，托管在 GitHub Releases 上。
        // 与 podspec 的 vendored_frameworks 保持一致，
        // 让 SPM 和 CocoaPods 两条构建路径始终同源。
        .binaryTarget(
            name: "FSAChatBottomContainer",
            url: "https://github.com/LinXunFeng/flutter_chat_packages_pub/releases/download/chat_bottom_container/ios_0.0.1.zip",
            checksum: "b9c380b72010e5d378cc813fbc5cca9b21471b82134e633567a6beee4b5a2a91"
        ),
        .target(
            name: "chat_bottom_container",
            dependencies: [
                "FSAChatBottomContainer",
                .product(name: "FlutterFramework", package: "FlutterFramework"),
            ]
        ),
    ]
)

这里有三个地方要重点说下。

第一个，预编译产物用 binaryTarget 引了个远程 zip。CocoaPods 侧一直是靠 podspec 的 prepare_command 用 curl 去 GitHub Releases 下载 xcframework。SPM 这边没必要另搞一套，直接让 binaryTarget 指向同一个 Release 的同一个 zip 。这个 zip 解开后根目录就是 FSAChatBottomContainer.xcframework，正好符合 binaryTarget 的要求，什么二进制都不用往仓库里塞。

第二个，checksum 不是可选的。SPM 引远程二进制强制要带校验和，不然直接报错。这个值用这条命令算：

swift package compute-checksum ios_0.0.1.zip

第三个，插件代码里 import Flutter 的那个模块，在 SPM 场景下是从哪来的？它是通过 .package(name: "FlutterFramework", path: "../FlutterFramework") 这条依赖拿到的，FlutterFramework 由 Flutter 工具在构建期动态注入进工程里。这里藏着个坑：这个依赖只有 Flutter 3.44+ 才有 ，后面 README 里那条版本下限，本质上就是被它卡出来的。

5、收尾：版本对齐和忽略产物

原来 podspec 的最低系统版本是 11.0，SPM / Flutter 这套要求更高，两边统一抬到 13.0：

s.platform = :ios, '13.0'          # podspec

platforms: [ .iOS("13.0") ],       // Package.swift

另外 SPM 一构建就会生成一堆本地缓存和锁文件，这些不该跟着提交，在 ios/.gitignore 里补三行来忽略掉：

.build/
.swiftpm/
Package.resolved

三、验证

这次改动最阴的地方在于：Flutter 的回退机制会让你以为在测 SPM，其实它悄悄走了 CocoaPods ，还以为新功能没问题。所以验证标准不是「能编译过」，而是得确认它到底走了哪条路。目标是让同一个 example 在两种模式下分别跑起来，而且各走各的、别串台。

1、CocoaPods 模式：先保证没坑到老用户

这次风险最高的就是老用户，源码搬了目录、source_files 也改了路径，稍有不慎就把 CocoaPods 这条路弄断。先关掉 SPM 跑一遍：

cd packages/chat_bottom_container/example
flutter config --no-enable-swift-package-manager   # 确保关闭 SPM
flutter clean
cd ios && rm -rf Pods Podfile.lock && pod install && cd ..
flutter build ios --simulator --debug

判断它确实走了 CocoaPods，看这几点：

• example/ios/Podfile.lock 里搜得到 chat_bottom_container
• example/ios/Pods/ 底下有这个 pod 的目录
• Frameworks/FSAChatBottomContainer.xcframework 被 prepare_command 下载出来了
• 能顺利编译到我搬家后的 Swift 源码，说明 source_files 的新路径没写错

2、SPM 模式：再证明新功能真的生效

再把 SPM 打开，重来一遍：

cd packages/chat_bottom_container/example
flutter config --enable-swift-package-manager      # 开启 SPM
flutter clean
cd ios && rm -rf Pods Podfile.lock && cd ..
flutter build ios --simulator --debug

这次看如下几点，确认它真的走 SPM，没偷偷回退：

• Flutter 生成了聚合包，打开 example/ios/Flutter/ephemeral/.../FlutterGeneratedPluginSwiftPackage/Package.swift，里面有 .package(name: "chat_bottom_container", path: ...) 这条依赖
• Podfile.lock 里已经找不到 chat_bottom_container 了（它从 Pods 里挪出去了，只剩 Flutter 本体）
• 构建日志打出了 Downloading binary artifact ...ios_0.0.1.zip，说明 binaryTarget 生效了
• 想确认它到底下到哪了，可以去 Xcode 的 DerivedData 里翻。SPM 由 Xcode 驱动，下载的 zip 会解压到 Runner 工程的 SourcePackages/artifacts/ 下，路径大致是：

~/Library/Developer/Xcode/DerivedData/Runner-<随机串>/SourcePackages/artifacts/chat_bottom_container/FSAChatBottomContainer/
# 里面就是解压出来的 FSAChatBottomContainer.xcframework

这一点和 CocoaPods 很不一样：CocoaPods 是 prepare_command 把 xcframework 下到插件仓库的 ios/Frameworks/ 里；SPM 则是丢进 Xcode 的 DerivedData 缓存，不进你的项目目录。

最省事的判断法：就看 Podfile.lock 里有没有这个插件。 有，就是 CocoaPods 在管；没有但 app 还能正常用，那就是 SPM 在管。

四、最后

版本兼容边界

最容易坑到使用者的是版本兼容这块，README 里也专门写了一段。原因就在前面的那个 FlutterFramework 依赖，它只有 Flutter 3.44+ 才有，兼容情况整理成一张表：

集成方式	Flutter 版本要求	说明
CocoaPods	无特殊要求	开箱即用，行为和以前完全一致
Swift Package Manager	3.44 及以上	3.44 起 SPM 默认开启
Swift Package Manager	3.24--3.43	虽然能手动开 SPM，但缺 FlutterFramework，请继续用 CocoaPods

所以老用户不用慌：只要不升级 Flutter、继续用 CocoaPods，这次改动对你没有任何影响。

附：3.44 上怎么关掉 SPM

如果升到了 3.44+，但暂时还想走 CocoaPods（比如某个依赖还没适配 SPM），可以主动把它关掉，分两个层级。

只对单个项目 关，在 app 的 pubspec.yaml 里 flutter: 下加一段 config:，这样会跟着仓库走、对所有协作者生效：

flutter:
  config:
    enable-swift-package-manager: false

对当前用户的所有项目 全局关，用命令行（也就是前面「验证」里跑 CocoaPods 模式那条）：

flutter config --no-enable-swift-package-manager

要注意，光「关掉」只是不再走 SPM，之前 flutter run 已经写进 Xcode 工程的 SPM 集成还留着。想彻底卸干净，得先 disable，再 flutter clean，然后进 Xcode 把 Package Dependencies 和 Frameworks, Libraries, and Embedded Content 里的 FlutterGeneratedPluginSwiftPackage 删掉，最后到 Product > Scheme > Edit Scheme → Build → Pre-actions 删掉 Run Prepare Flutter Framework Script。

两条路径必须同源

SPM 和 CocoaPods 引用的源码、二进制、最低版本，必须完全一致。一旦两边各维护一套，某次版本升级就会冒出「用 CocoaPods 和用 SPM 的人拿到两份不同实现」的问题，排查起来很麻烦。所以源码都指向 Sources/、二进制都锁同一个 Release、最低版本都写 13.0。

由此还带出一个发版时的坑：以后 xcframework 更新了，podspec 的版本/URL 和 Package.swift 的 url + checksum 得一起改 ，漏掉哪个都会两边不同步。这一点我在 Package.swift 里写了注释提醒。

支持 SPM 的步骤清单

如果你也有插件需要支持 SPM ，照着如下步骤去做即可：

1. 源码挪到 Sources/<target>/ 布局，podspec 的 source_files 跟着改；
2. pigeon 之类代码生成工具的输出路径同步更新，别留孤儿文件；
3. 新增 Package.swift，预编译产物用 binaryTarget 引同一个 Release，checksum 用 swift package compute-checksum 算；
4. 靠 FlutterFramework 拿到 Flutter 模块，并据此把版本下限定在 Flutter 3.44+；
5. 最低系统版本两边对齐（我这次是 13.0）；
6. .gitignore 忽略 .build/、.swiftpm/、Package.resolved；
7. 保留 podspec ，README 里把版本兼容边界写清楚；
8. CocoaPods / SPM 两种模式各验一遍，用 Podfile.lock 判断实际走了哪条路。

相关链接：

• 仓库：flutter_chat_packages
• Issue：#39
• PR：#40
• 官方文档：Swift Package Manager for app developers

这次的记录就到这，希望对同样在补 SPM 的你有帮助。

如果文章对您有所帮助, 请不吝点击关注一下我的微信公众号：FSA全栈行动, 这将是对我最大的激励. 公众号不仅有 iOS 技术，还有 Android，Flutter，Python 等文章, 可能有你想要了解的技能知识点哦~