02-构建打包指南¶

Vexfy 项目多平台构建打包指南

一、打包前准备¶

# 1. 进入 Flutter 项目目录
cd ~/workspace/vex/vexfy/app

# 2. 清理构建缓存（可选，推荐）
flutter clean

# 3. 安装依赖
flutter pub get

# 4. 验证环境
flutter doctor

二、Android APK¶

2.1 Debug 版（测试用）¶

flutter build apk --debug

# 输出：build/app/outputs/flutter-apk/app-debug.apk

2.2 Release 版（发布用）¶

flutter build apk --release

# 输出：build/app/outputs/flutter-apk/app-release.apk

2.3 Split APK（减小体积）¶

flutter build apk --release --split-per-abi

# 输出：
# app-arm64-v8a-release.apk  （ARM64）
# app-armeabi-v7a-release.apk （ARM32）
# app-x86_64-release.apk （x86_64模拟器用）

2.4 Android 环境变量¶

export ANDROID_HOME=~/Apps/android-sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools

三、Linux 桌面应用¶

3.1 安装 Linux 桌面开发依赖（Ubuntu/Debian）¶

sudo apt update
sudo apt install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-12-dev

3.2 构建 Linux App¶

flutter build linux --release

# 输出：build/linux/x64/release/bundle/

3.3 目录结构¶

build/linux/x64/release/bundle/
├── vexfy              ← 可执行文件
├── lib/                ← 依赖库
└── data/               ← 资源文件

3.4 分发¶

将 bundle/ 目录打包分发，用户无需安装 Flutter 运行环境。

四、Windows 桌面应用¶

4.1 安装 Windows 桌面开发依赖¶

在 Windows 上：

# 1. 安装 Visual Studio 2022（桌面开发 C++ 工具）
# 2. 安装 Flutter SDK
# 3. 启用 Windows 桌面支持
flutter config --enable-windows-desktop

# 4. 安装依赖
flutter doctor

4.2 构建 Windows App¶

flutter build windows --release

# 输出：build/windows/runner/Release/

4.3 分发¶

build/windows/runner/Release/
├── vexfy.exe              ← 主程序
├── vexfy.pdb               ← 调试符号（可选）
├── flutter_windows.dll     ← Flutter 引擎
└── data/                   ← 资源文件

五、iOS（仅 macOS）¶

5.1 前置要求¶

# 1. 安装 Xcode（App Store 免费安装）
xcode-select --install

# 2. 同意许可协议
sudo xcodebuild -license accept

# 3. 配置 iOS 模拟器
open -a Simulator

5.2 构建 iOS 模拟器版（调试用）¶

flutter build ios --simulator --no-codesign

# 输出：build/ios/iphonesimulator/

5.3 构建 iOS 真机版（需要签名）¶

flutter build ios --release --no-codesign

# 需要配置：
# 1. Apple Developer 账号
# 2. Bundle Identifier
# 3. 代码签名证书

5.4 部署到真机¶

# 在 Xcode 中：
# 1. 打开 ios/Runner.xcworkspace
# 2. 配置签名（Signing & Capabilities）
# 3. 选择目标设备
# 4. 点击 Run

六、macOS（仅 macOS）¶

6.1 前置要求¶

# 1. 安装 Xcode
xcode-select --install

# 2. 启用 macOS 桌面支持
flutter config --enable-macos-desktop

6.2 构建 macOS App¶

flutter build macos --release

# 输出：build/macos/Build/Products/Release/

6.3 目录结构¶

build/macos/Build/Products/Release/vexfy.app/
├── Contents/
│   ├── MacOS/vexfy       ← 可执行文件
│   ├── Resources/        ← 资源文件
│   └── Info.plist        ← 应用配置

6.4 分发方式¶

方式	说明
`.app` 打包	直接分发，用户双击安装
DMG 镜像	打包成磁盘镜像分发
Mac App Store	需要付费开发者账号

七、一键构建脚本¶

在项目根目录创建 scripts/build.sh：

#!/bin/bash
# 构建脚本：支持多平台

set -e

cd "$(dirname "$0")/app"

echo "=== 清理 ==="
flutter clean

echo "=== 安装依赖 ==="
flutter pub get

echo ""
echo "请选择平台："
echo "1. Android APK (debug)"
echo "2. Android APK (release)"
echo "3. Linux"
echo "4. Windows"
echo "5. iOS (需要 macOS)"
echo "6. macOS (需要 macOS)"
read -p "选择 (1-6): " choice

case $choice in
    1) flutter build apk --debug ;;
    2) flutter build apk --release ;;
    3) flutter build linux --release ;;
    4) flutter build windows --release ;;
    5) flutter build ios --simulator --no-codesign ;;
    6) flutter build macos --release ;;
esac

echo ""
echo "=== 构建完成 ==="
echo "输出目录：build/"

运行：

chmod +x scripts/build.sh
./scripts/build.sh

八、构建输出位置汇总¶

平台	输出路径
Android Debug APK	`build/app/outputs/flutter-apk/app-debug.apk`
Android Release APK	`build/app/outputs/flutter-apk/app-release.apk`
Linux	`build/linux/x64/release/bundle/`
Windows	`build/windows/runner/Release/`
iOS Simulator	`build/ios/iphonesimulator/`
macOS	`build/macos/Build/Products/Release/vexfy.app`

九、常见问题¶

Q: Android 打包失败，提示 SDK 版本不对？¶

# 检查并安装正确版本
flutter doctor -v
flutter config --android-sdk ~/Apps/android-sdk

Q: iOS 构建提示需要签名？¶

# 使用 --no-codesign 跳过签名（仅用于测试）
flutter build ios --simulator --no-codesign

Q: Linux 构建提示缺少依赖？¶

# Ubuntu/Debian
sudo apt install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev

# Fedora
sudo dnf install clang cmake ninja-build gtk3-devel

下一步¶

03-Widget基础 — 写个简单界面