客户端打包教程

# 打包教程

适用：Flutter 客户端（Android / iOS / Windows / macOS）
目标：修改后端接口地址并完成多端打包发布

0) 打包前通用准备

确认环境

flutter --version 与 flutter doctor 无红项

Android：已装 JDK + Android SDK

iOS：仅 macOS，Xcode 可用

Windows：安装 Visual Studio（含 C++ 工具链）

更新依赖与清理

（可选）版本号调整
在 pubspec.yaml 中修改：

其中 1.2.3 是版本名，45 是构建号。

第一部分：环境配置与接口修改（核心）

小白傻瓜版（只看这一节也能打包）

目标：把“后端地址”换成你自己的，然后按步骤打包。

你需要知道的 3 个概念（超简版）

REST API 地址：App 访问后端接口的入口，写在 serverUrl。

WebSocket 地址：用于实时消息，写在 wsUrl。

生产环境：正式上线可用的域名，一般是 HTTPS。

步骤 1：改接口地址（最关键）

打开文件：lib/core/services/api/api_client.dart

找到以下两行，把域名改成你自己的：

改成你的生产域名，例如：

小白提示：
serverUrl 是 HTTP 接口地址
wsUrl 是 WebSocket 地址
两个协议必须一致：https 对应 wss
baseUrl 不用改，它会自动拼接成 https://your-domain.com/api/v1

步骤 1.1：怎么判断后端地址写对了？

打开浏览器访问：

https://你的域名/api/v1

如果后端正常，会返回 JSON 或提示信息（不是 404）。

如果报错，先找后端开发确认服务是否启动。

步骤 2：如果你有管理后台（admin）

打开文件：admin/.env.production

找到这一行并替换：

VITE_API_URL = https://im.yi-ruan.com/api/v1

改成你自己的后端地址：

VITE_API_URL = https://your-domain.com/api/v1

小白提示：
admin/.env.production 是发布用配置
开发本地联调时，才用 admin/.env.development

步骤 3：Android 打包（最常用）

在项目根目录执行：

直接打包 APK：

输出位置：

build/app/outputs/flutter-apk/app-release.apk

小白提示：
如果你只想快速测试，可以先用 debug 签名（已内置）。
要发布到应用市场必须配置正式签名，见下文“Android 签名配置”。

步骤 3.1：常见 Android 打包错误

Execution failed for task :app:bundleRelease
通常是签名没配或 JDK 版本不对。

uses-sdk:minSdkVersion 30 cannot be smaller
说明设备太老，项目只支持 Android 11+。

Keystore was tampered
说明签名文件或密码不对。

步骤 4：iOS 打包（需要 macOS）

安装 iOS 依赖：

打包：

输出位置：

build/ios/ipa/*.ipa

小白提示：
iOS 打包一定需要 Mac + Xcode。
如果没有 Mac，需要找人帮忙或使用云构建。

步骤 5：Windows / macOS 桌面版

开启桌面支持：

构建：

小白提示：
Windows 需要安装 Visual Studio（带 C++ 开发组件）。
macOS 需要安装 Xcode 和命令行工具。

步骤 6：打包后怎么验证

安装到手机或模拟器

登录账号，发一条消息

退出再进入，消息能否同步

上传一张图片，看是否能打开

1) 接口地址修改位置（已在代码中确认）

主要配置集中在：

lib/core/services/api/api_client.dart

关键变量（需要修改）：

ApiConfig.serverUrl

ApiConfig.wsUrl

ApiConfig.baseUrl（由 serverUrl 拼接，不需要手动改）

示例（生产环境建议 https / wss）：

开发/测试切换说明：

ApiConfig 内已有本地开发地址（注释状态），按需切换注释即可。

未发现 flavor / .env / isPro / debugMode 相关开关，接口只在 ApiConfig 集中配置。

注意事项：

serverUrl 与 wsUrl 协议必须匹配（http ↔ ws，https ↔ wss）。

媒体/文件地址会通过 ApiConfig.getMediaUrl() 拼接，serverUrl 必须指向同一域名。

如需调整“邀请链接”域名，请检查：
lib/features/settings/pages/profile_page.dart

2) 接口地址修改清单（带行号）

Flutter 客户端（必须改）

文件（含行号）	变量/内容	说明
`lib/core/services/api/api_client.dart:14`	`serverUrl`	REST API 主域名
`lib/core/services/api/api_client.dart:15`	`wsUrl`	WebSocket 地址
`lib/core/services/api/api_client.dart:11`	`serverUrl`（注释）	本地开发示例
`lib/core/services/api/api_client.dart:12`	`wsUrl`（注释）	本地开发示例

管理后台（如部署后台）

文件（含行号）	变量/内容	说明
`admin/.env.development:13`	`VITE_API_PROXY_URL`	本地开发代理后端
`admin/.env.development:10`	`VITE_API_URL`	前端请求前缀
`admin/.env.production:7`	`VITE_API_URL`	生产后端地址
`admin/.env.production:4`	`VITE_BASE_URL`	后台部署子路径（如 `/admin/`）
`admin/.env:10`	`VITE_BASE_URL`	通用默认值

可选检查（非接口，但可能包含硬编码域名）

文件（含行号）	内容	说明
`lib/features/settings/pages/profile_page.dart:1005`	邀请链接域名	复制分享时的域名
`lib/features/moments/pages/moments_page.dart:7426`	`localhost` 替换	本地 URL 兼容逻辑

第二部分：Android 打包流程

1) 签名配置（必做）

本项目使用 Kotlin DSL：

android/app/build.gradle.kts

当前 release 使用的是 debug 签名，需要改为正式签名：

请替换为 release 签名配置。

生成 keystore（示例）

创建 android/key.properties

在 build.gradle.kts 中加载 key.properties（示意，需按你项目结构调整）

2) 构建命令

生成 APK（发布版）：

生成 AAB（Google Play 推荐）：

项目自带脚本（仅 arm64 + 混淆）：

脚本输出位置：

build/app/outputs/flutter-apk/app-release.apk

混淆符号：build/app/outputs/symbols/

3) 输出产物路径

APK：build/app/outputs/flutter-apk/app-release.apk

AAB：build/app/outputs/bundle/release/app-release.aab

备注：当前工程仅保留 arm64-v8a 架构，如需兼容更多设备请调整 abiFilters。

第三部分：iOS 打包流程（macOS）

1) 安装依赖

2) Xcode 设置

打开 ios/Runner.xcworkspace，在 Signing & Capabilities 中：

选择 Team

设置 Bundle Identifier

确认 Profile / Certificate 生效

3) 构建命令

4) 输出路径

build/ios/ipa/*.ipa

备注：ios/Podfile 设定最低 iOS 版本为 15.0，旧设备无法安装。

第四部分：PC 端打包流程（Windows/macOS）

1) 开启桌面支持

2) 构建命令

Windows：

macOS：

3) 输出路径

Windows：build/windows/x64/runner/Release/

macOS：build/macos/Build/Products/Release/

备注：桌面发布如需签名/公证（macOS）或签名（Windows），需额外配置证书工具链。

第五部分：打包后快速自检清单

启动应用是否能登录 / 拉取消息

WebSocket 是否能正常连接（无频繁重连日志）

上传/下载媒体是否可用（图片/语音/文件）

iOS/Android 通知权限是否正常

第六部分：生产环境网络安全配置（非常重要）

Android（HTTP/HTTPS）

当前清单中允许明文流量：

android/app/src/main/AndroidManifest.xml
android:usesCleartextTraffic="true"

生产环境建议：

后端必须启用 https / wss

将 usesCleartextTraffic 改为 false

更新网络安全配置：

android/app/src/main/res/xml/network_security_config.xml

删除/注释 cleartextTrafficPermitted="true" 的本地域名段

iOS（ATS）

当前 Info.plist 中允许任意明文：

ios/Runner/Info.plist
NSAllowsArbitraryLoads = true

生产环境建议：

关闭 NSAllowsArbitraryLoads

保持后端域名全 HTTPS

第七部分：版本号与构建参数（发布前必看）

1) `pubspec.yaml` 版本号

1.2.3：对外版本号

45：构建号（Android versionCode / iOS build）

2) 构建时指定版本

3) Android 最低版本与 ABI

在 android/app/build.gradle.kts 中已设置：

minSdk = 30（Android 11+）

仅保留 arm64-v8a

如需兼容更低系统或更多架构，请调整：

minSdk

ndk.abiFilters

第八部分：混淆与符号文件（Crash 排查用）

Android

项目脚本默认开启：

--obfuscate

--split-debug-info=build/app/outputs/symbols

请妥善保存以下文件：

build/app/outputs/symbols/（Flutter 符号）

R8 mapping.txt（位于 build/app/outputs/mapping/release/）

iOS（可选）

同样支持 Flutter 混淆：

第九部分：常见问题排查

Android 不能访问 HTTP

检查 usesCleartextTraffic 与 network_security_config.xml

iOS 无法访问接口

检查 NSAllowsArbitraryLoads 是否关闭 + 后端是否 HTTPS

WebSocket 连接失败

wsUrl 必须与 serverUrl 协议匹配

生产必须 wss

仅 arm64 包无法在模拟器运行

当前配置移除了 x86_64 与 armeabi-v7a

如需模拟器或 32 位设备，修改 abiFilters

第十部分：上线前注意事项总览（尽量别漏）

接口与域名

后端需同时提供：/api/v1 与 /api/v1/ws（与 serverUrl / wsUrl 对齐）

生产务必使用 https + wss，移动端不要使用自签证书

管理端 .env.production 的 VITE_API_URL 要与客户端一致

网络安全

Android：生产关闭 usesCleartextTraffic，移除本地 HTTP 域名

iOS：关闭 NSAllowsArbitraryLoads，确保全站 HTTPS

签名与证书

Android：release.keystore 与 key.properties 必须备份

iOS：确保签名 Team、Bundle ID、Provisioning Profile 一致

macOS：如需公证，请准备 Apple Developer 证书与 App Store Connect 权限

版本与兼容性

minSdk = 30（仅支持 Android 11+），如需兼容低版本必须下调

仅 arm64-v8a，如需模拟器或旧机型，增加 x86_64/armeabi-v7a

iOS 最低版本为 15.0（见 Podfile）

混淆与崩溃追踪

Android 保存 mapping.txt 与 symbols，用于崩溃回溯

iOS 如开启混淆，同样保存 split-debug-info

推送 / 通话 / 权限

iOS/Android 推送需正确配置证书/凭据

CallKit/VoIP、麦克风、相机权限需在权限说明中完整配置

构建一致性

打包前先 flutter clean，避免缓存污染

CI/CD 中固定 Flutter 版本，避免本地与流水线不一致

0) 打包前通用准备#

第一部分：环境配置与接口修改（核心）#

小白傻瓜版（只看这一节也能打包）#

你需要知道的 3 个概念（超简版）#

步骤 1：改接口地址（最关键）#

步骤 1.1：怎么判断后端地址写对了？#

步骤 2：如果你有管理后台（admin）#

步骤 3：Android 打包（最常用）#

步骤 3.1：常见 Android 打包错误#

步骤 4：iOS 打包（需要 macOS）#

步骤 5：Windows / macOS 桌面版#

步骤 6：打包后怎么验证#

1) 接口地址修改位置（已在代码中确认）#

2) 接口地址修改清单（带行号）#

第二部分：Android 打包流程#

1) 签名配置（必做）#

2) 构建命令#

3) 输出产物路径#

第三部分：iOS 打包流程（macOS）#

1) 安装依赖#

2) Xcode 设置#

3) 构建命令#

4) 输出路径#

第四部分：PC 端打包流程（Windows/macOS）#

1) 开启桌面支持#

2) 构建命令#

3) 输出路径#

第五部分：打包后快速自检清单#

第六部分：生产环境网络安全配置（非常重要）#

Android（HTTP/HTTPS）#

iOS（ATS）#

第七部分：版本号与构建参数（发布前必看）#

1) pubspec.yaml 版本号#

2) 构建时指定版本#

3) Android 最低版本与 ABI#

第八部分：混淆与符号文件（Crash 排查用）#

Android#

iOS（可选）#

第九部分：常见问题排查#

第十部分：上线前注意事项总览（尽量别漏）#

0) 打包前通用准备

第一部分：环境配置与接口修改（核心）

小白傻瓜版（只看这一节也能打包）

你需要知道的 3 个概念（超简版）

步骤 1：改接口地址（最关键）

步骤 1.1：怎么判断后端地址写对了？

步骤 2：如果你有管理后台（admin）

步骤 3：Android 打包（最常用）

步骤 3.1：常见 Android 打包错误

步骤 4：iOS 打包（需要 macOS）

步骤 5：Windows / macOS 桌面版

步骤 6：打包后怎么验证

1) 接口地址修改位置（已在代码中确认）

2) 接口地址修改清单（带行号）

第二部分：Android 打包流程

1) 签名配置（必做）

2) 构建命令

3) 输出产物路径

第三部分：iOS 打包流程（macOS）

1) 安装依赖

2) Xcode 设置

3) 构建命令

4) 输出路径

第四部分：PC 端打包流程（Windows/macOS）

1) 开启桌面支持

2) 构建命令

3) 输出路径

第五部分：打包后快速自检清单

第六部分：生产环境网络安全配置（非常重要）

Android（HTTP/HTTPS）

iOS（ATS）

第七部分：版本号与构建参数（发布前必看）

1) `pubspec.yaml` 版本号

2) 构建时指定版本

3) Android 最低版本与 ABI

第八部分：混淆与符号文件（Crash 排查用）

Android

iOS（可选）

第九部分：常见问题排查

第十部分：上线前注意事项总览（尽量别漏）