常见问题
下面是开发 FoxTalk 时最常被问的几个问题。还没覆盖到的可以在 GitHub 提 issue。
Q · Flutter / Dart SDK 应该用哪个版本?
跟 pubspec.lock 里的 Flutter 版本一致即可。当前主仓在 Flutter 3.x / Dart 3.x 上验证通过。不建议跨大版本升级 SDK, 升级前先在 feature branch 跑一遍 analyze + 真机装机自测。
Q · main.dart / main_free.dart / main_pro.dart 三个入口有什么区别?
main.dart 是默认入口, 走 app_modules.dart 注册全部 15 个扩展模块。main_free.dart 走 module_profile_free.dart 仅注册基础模块, 只注册基础模块。main_pro.dart 走 module_profile_pro.dart 注册模块组合。日常开发用 main.dart 即可。
Q · 为什么用 packages/wukongimfluttersdk_patched 而不是 pub 的版本?
上游 wukongimfluttersdk 在跨平台 / 边缘场景有几处 bug (例如消息 decode 异常 / 引用消息 readInt String-index crash), FoxTalk 在本仓内 vendor 一份 patched 版本, 通过 pubspec_overrides 走本地路径。改完会回上游 PR, 等 upstream merge 后再切回 pub。
Q · prod 与 dev 服务端怎么切?
AppConfig 默认指向 https://your-server.example (prod), 适合 TF / App Store / Release。本地开发连局域网服务端用 flutter run --dart-define=CHATIM_SERVER_BASE_URL=http://<LAN_IP>:8090 覆盖。详见 /dev/config 项目配置。
Q · iOS aps-environment 报错怎么修?
通常是 Xcode 自动签名时 entitlements 不匹配。确认 Runner target → Signing & Capabilities 里的 Team 是 <YOUR_TEAM_ID> (或你的 team), Push Notifications capability 已添加, Bundle ID com.example.app 在 Apple Developer 后台开启了 Push Notifications service。
Q · 真机连本地 server 用哪个 IP?
用电脑的局域网 IP (Mac 上 ipconfig getifaddr en0), 不要用 127.0.0.1 / localhost — 真机访问的是手机自己的 localhost。WuKongIM TCP 端口默认 5100, WS 端口 5200, Go API 端口 8090, 确认电脑防火墙没拦这些端口。
Q · 怎么新增一个扩展模块?
5 步: 在 module_ids.dart 加 ID 常量, 新建 lib/src/<module>/<module>_module.dart 实现 FeatureModule, 写模块内部源码, 在 app_modules.dart 顶部 import + registerModules 里调一次 register, 真机装机自测。详见 /dev/modules 增强模块。
last updated · 2026-06