02-从零到一-Flutter+Taro双栈打造全平台产品

🚀 从零到一：用 Flutter + Taro 双栈打造全平台产品

一个产品要覆盖 iOS、Android、微信小程序、H5，甚至鸿蒙……用一个框架？根本不现实。 用四个框架？维护成本爆炸。双栈组合才是 2026 年全平台的最优解。

核心策略：Flutter 主攻原生 App（iOS / Android / 桌面），Taro 主攻小程序 + H5（微信 / 支付宝 / 抖音 / Web）。两个框架各做擅长的事，通过共享设计规范、API 层和业务逻辑实现统一产品体验。

---

📊 全局架构总览

层级	职责	技术选型	共享程度
🎨 设计层	UI/UX 规范、设计 Token	Figma + 统一 Design Token	✅ 完全共享
📡 API 层	接口定义、数据模型	OpenAPI / GraphQL Schema	✅ 完全共享
🧠 业务逻辑层	核心业务规则	独立微服务 / BFF	✅ 完全共享
📱 App 端	iOS / Android / 桌面	Flutter（Dart）	🔵 Flutter 独占
🔷 小程序 + H5 端	微信 / 支付宝 / 抖音 / Web	Taro（React + TypeScript）	🟢 Taro 独占

---

🏗 1. 架构设计：双栈如何协同？

整体分层架构

┌─────────────────────────────────────────────────────┐
│                   产品设计层                          │
│         Figma Design System + Design Tokens          │
└──────────────────────┬──────────────────────────────┘
                       │ 统一设计规范
          ┌────────────┴────────────┐
          │                         │
┌─────────▼─────────┐   ┌──────────▼──────────┐
│   Flutter App 端   │   │   Taro 小程序/H5 端  │
│  iOS / Android /   │   │  微信 / 支付宝 /     │
│  macOS / Windows   │   │  抖音 / H5           │
└─────────┬─────────┘   └──────────┬──────────┘
          │                         │
          └────────────┬────────────┘
                       │ 统一 API 协议
          ┌────────────▼────────────┐
          │     BFF / API Gateway    │
          │   统一接口 + 数据适配     │
          └────────────┬────────────┘
                       │
          ┌────────────▼────────────┐
          │     后端微服务集群        │
          │  用户 / 订单 / 支付 / …  │
          └─────────────────────────┘

为什么是 Flutter + Taro，而不是其他组合？

组合方案	✅ 优势	❌ 劣势
Flutter + Taro	App 性能顶级 + 小程序全覆盖	两套代码，需统一规范
Flutter + UniApp	App 性能好 + 小程序简单上手	UniApp 生态较封闭，React 团队不友好
RN + Taro	都是 JS/TS，语言统一	RN App 性能不及 Flutter
纯 UniApp	一套代码全覆盖	App 端性能瓶颈，复杂动画吃力
纯 Flutter	App + Web + 桌面一把梭	不支持小程序，Web SEO 弱

🔑 关键决策：团队如果是 React 技术栈，Taro 几乎零学习成本； Flutter 虽然需要学 Dart，但 Dart 语法对 TypeScript 开发者非常友好， 上手成本远低于预期。

---

🎨 2. 设计层共享：Design Token 统一两端

Design Token 是双栈协同的第一块基石。把颜色、字号、间距、圆角等设计决策抽象为 Token，两端各自消费。

Token 定义（JSON 格式）

{
  "color": {
    "primary": { "value": "#6366F1", "type": "color" },
    "primary-light": { "value": "#A5B4FC", "type": "color" },
    "secondary": { "value": "#EC4899", "type": "color" },
    "bg-primary": { "value": "#0F172A", "type": "color" },
    "bg-secondary": { "value": "#1E293B", "type": "color" },
    "text-primary": { "value": "#F8FAFC", "type": "color" },
    "text-secondary": { "value": "#94A3B8", "type": "color" },
    "success": { "value": "#10B981", "type": "color" },
    "warning": { "value": "#F59E0B", "type": "color" },
    "error": { "value": "#EF4444", "type": "color" }
  },
  "spacing": {
    "xs": { "value": "4px", "type": "spacing" },
    "sm": { "value": "8px", "type": "spacing" },
    "md": { "value": "16px", "type": "spacing" },
    "lg": { "value": "24px", "type": "spacing" },
    "xl": { "value": "32px", "type": "spacing" }
  },
  "fontSize": {
    "xs": { "value": "12px", "type": "fontSize" },
    "sm": { "value": "14px", "type": "fontSize" },
    "base": { "value": "16px", "type": "fontSize" },
    "lg": { "value": "18px", "type": "fontSize" },
    "xl": { "value": "20px", "type": "fontSize" },
    "2xl": { "value": "24px", "type": "fontSize" },
    "3xl": { "value": "30px", "type": "fontSize" }
  },
  "borderRadius": {
    "sm": { "value": "4px", "type": "borderRadius" },
    "md": { "value": "8px", "type": "borderRadius" },
    "lg": { "value": "12px", "type": "borderRadius" },
    "full": { "value": "9999px", "type": "borderRadius" }
  }
}

Flutter 端消费 Token

// lib/config/design_tokens.dart
class DesignTokens {
  // Colors
  static const Color primary = Color(0xFF6366F1);
  static const Color primaryLight = Color(0xFFA5B4FC);
  static const Color secondary = Color(0xFFEC4899);
  static const Color bgPrimary = Color(0xFF0F172A);
  static const Color bgSecondary = Color(0xFF1E293B);
  static const Color textPrimary = Color(0xFFF8FAFC);
  static const Color textSecondary = Color(0xFF94A3B8);

  // Spacing
  static const double spacingXs = 4.0;
  static const double spacingSm = 8.0;
  static const double spacingMd = 16.0;
  static const double spacingLg = 24.0;
  static const double spacingXl = 32.0;

  // Font Size
  static const double fontSizeXs = 12.0;
  static const double fontSizeSm = 14.0;
  static const double fontSizeBase = 16.0;
  static const double fontSizeLg = 18.0;
  static const double fontSizeXl = 20.0;

  // Border Radius
  static const double radiusSm = 4.0;
  static const double radiusMd = 8.0;
  static const double radiusLg = 12.0;
}

Taro 端消费 Token

// src/styles/tokens.scss
$color-primary: #6366F1;
$color-primary-light: #A5B4FC;
$color-secondary: #EC4899;
$color-bg-primary: #0F172A;
$color-bg-secondary: #1E293B;
$color-text-primary: #F8FAFC;
$color-text-secondary: #94A3B8;

$spacing-xs: 8rpx;    // 小程序用 rpx
$spacing-sm: 16rpx;
$spacing-md: 32rpx;
$spacing-lg: 48rpx;
$spacing-xl: 64rpx;

$font-size-xs: 24rpx;
$font-size-sm: 28rpx;
$font-size-base: 32rpx;
$font-size-lg: 36rpx;
$font-size-xl: 40rpx;

$radius-sm: 8rpx;
$radius-md: 16rpx;
$radius-lg: 24rpx;

Token 同步工作流

Figma Design Token 插件导出 JSON
        → 自动化脚本转换
        ├── → Flutter: design_tokens.dart
        └── → Taro: tokens.scss + tokens.ts

🔑 实战建议：使用 Style Dictionary 作为 Token 转换引擎，一份 JSON 自动输出 Dart / SCSS / TypeScript 多种格式。

---

📡 3. API 层共享：一份契约，两端消费

OpenAPI 驱动的接口共享

# api/openapi.yaml — 唯一真相来源
openapi: 3.0.3
info:
  title: 全平台产品 API
  version: 1.0.0

paths:
  /api/products:
    get:
      summary: 获取商品列表
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:     { type: string }
        name:   { type: string }
        price:  { type: number }
        image:  { type: string }
        desc:   { type: string }

    ProductListResponse:
      type: object
      properties:
        list:   { type: array, items: { $ref: '#/components/schemas/Product' } }
        total:  { type: integer }
        page:   { type: integer }

自动生成两端代码

# Flutter 端 — 生成 Dart 模型 + API 客户端
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g dart-dio \
  -o flutter_app/packages/api_client

# Taro 端 — 生成 TypeScript 类型 + 请求函数
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-axios \
  -o taro_app/src/api/generated

API 共享效果对比

维度	✅ 共享后	❌ 不共享
接口同步	改一处 YAML，两端自动更新	手动同步，容易遗漏字段
类型安全	编译期检查，字段类型一致	运行时才发现类型不匹配
联调效率	前后端契约明确，并行开发	接口文档过时，反复沟通
维护成本	一份 Schema 维护	两端各维护一套模型

---

📱 4. Flutter 端实战：App 侧的核心架构

推荐技术栈

Flutter App 技术栈
├── 状态管理：Riverpod 3.x（@riverpod 代码生成）
├── 路由导航：GoRouter（声明式 + 认证守卫）
├── 网络请求：Dio + 自动生成的 API Client
├── 数据模型：Freezed 不可变模型
├── 本地存储：Hive CE（AES-256 加密）
├── 依赖注入：get_it + injectable
└── 国际化：Easy Localization

商品列表页示例

// lib/features/product/presentation/controllers/product_controller.dart
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'product_controller.g.dart';

@riverpod
class ProductController extends _$ProductController {
  int _page = 1;
  final int _pageSize = 20;

  @override
  Future<List<Product>> build() async {
    return _fetchProducts();
  }

  Future<List<Product>> _fetchProducts() async {
    final response = await ref.read(productRepositoryProvider).getProducts(
      page: _page,
      pageSize: _pageSize,
    );
    return response.list;
  }

  Future<void> loadMore() async {
    _page++;
    final moreProducts = await _fetchProducts();
    state = AsyncData([...state.value ?? [], ...moreProducts]);
  }

  Future<void> refresh() async {
    _page = 1;
    state = const AsyncLoading();
    state = await AsyncValue.guard(() => _fetchProducts());
  }
}

// lib/features/product/presentation/screens/product_screen.dart
class ProductScreen extends ConsumerWidget {
  const ProductScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final productState = ref.watch(productControllerProvider);

    return Scaffold(
      backgroundColor: DesignTokens.bgPrimary,
      appBar: AppBar(
        title: Text('商品列表', style: TextStyle(
          fontSize: DesignTokens.fontSizeXl,
          color: DesignTokens.textPrimary,
        )),
        backgroundColor: DesignTokens.bgSecondary,
      ),
      body: productState.when(
        data: (products) => RefreshIndicator(
          onRefresh: () => ref.read(productControllerProvider.notifier).refresh(),
          child: ListView.builder(
            padding: EdgeInsets.all(DesignTokens.spacingMd),
            itemCount: products.length,
            itemBuilder: (_, i) => ProductCard(product: products[i]),
          ),
        ),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => Center(child: Text('加载失败: $e')),
      ),
    );
  }
}

---

🔷 5. Taro 端实战：小程序侧的核心架构

推荐技术栈

Taro 小程序 + H5 技术栈
├── 框架版本：Taro 4.x + React 18
├── 语言：TypeScript（严格模式）
├── 状态管理：Zustand（轻量 + React 友好）
├── UI 组件：NutUI-React（京东出品，Taro 原生适配）
├── 请求库：Taro.request 封装 + 自动生成类型
├── CSS 方案：SCSS Module + Design Token
└── 构建目标：微信 / 支付宝 / 抖音 / H5

商品列表页示例

// src/pages/product/index.tsx
import { View, Text } from '@tarojs/components'
import { usePageScroll } from '@tarojs/taro'
import { useProductStore } from '@/stores/product'
import { ProductCard } from '@/components/ProductCard'
import styles from './index.module.scss'

const ProductPage = () => {
  const { products, loading, loadMore, refresh } = useProductStore()

  // 下拉刷新
  usePullDownRefresh(async () => {
    await refresh()
    Taro.stopPullDownRefresh()
  })

  // 触底加载
  useReachBottom(() => {
    loadMore()
  })

  return (
    <View className={styles.container}>
      <View className={styles.header}>
        <Text className={styles.title}>商品列表</Text>
      </View>

      <View className={styles.productList}>
        {products.map((product) => (
          <ProductCard key={product.id} product={product} />
        ))}
      </View>

      {loading && (
        <View className={styles.loadingTip}>
          <Text>加载中...</Text>
        </View>
      )}
    </View>
  )
}

export default ProductPage

// src/pages/product/index.module.scss
@import '@/styles/tokens.scss';

.container {
  min-height: 100vh;
  background-color: $color-bg-primary;
  padding: $spacing-md;
}

.header {
  margin-bottom: $spacing-lg;
}

.title {
  font-size: $font-size-xl;
  color: $color-text-primary;
  font-weight: 700;
}

.productList {
  display: flex;
  flex-direction: column;
  gap: $spacing-md;
}

.loadingTip {
  text-align: center;
  padding: $spacing-lg;
  color: $color-text-secondary;
}

---

🔄 6. 双端同页面对比：看两端如何殊途同归

以商品卡片组件为例，对比 Flutter 和 Taro 的实现差异：

维度	🐦 Flutter	🔷 Taro
语言	Dart	TypeScript + JSX
布局方式	Row / Column / Padding	View + Flexbox CSS
样式引用	DesignTokens.primary	$color-primary（SCSS）
图片加载	CachedNetworkImage	Image 组件（原生优化）
点击事件	GestureDetector / InkWell	onClick prop
状态管理	ref.watch(provider)	useStore() Hook
列表渲染	ListView.builder	Array.map()
动画	AnimationController / Hero	CSS Transition / Animation

虽然语法不同，但产品体验完全一致 — 因为共享了 Design Token 和 API 契约。

---

🗂 7. 项目结构：Monorepo 组织方式

my-product/                       # Monorepo 根目录
├── packages/
│   ├── design-tokens/            # 🎨 共享设计 Token
│   │   ├── tokens.json           # 唯一真相来源
│   │   ├── scripts/
│   │   │   ├── gen-dart.js       # → Flutter design_tokens.dart
│   │   │   └── gen-scss.js       # → Taro tokens.scss
│   │   └── package.json
│   │
│   └── api-schema/               # 📡 共享 API 定义
│       ├── openapi.yaml          # 唯一真相来源
│       ├── scripts/
│       │   ├── gen-dart.sh       # → Flutter API Client
│       │   └── gen-ts.sh         # → Taro TypeScript 类型
│       └── package.json
│
├── flutter_app/                  # 📱 Flutter 端
│   ├── lib/
│   │   ├── config/
│   │   │   └── design_tokens.dart  # ← 自动生成
│   │   ├── features/
│   │   └── packages/
│   │       └── api_client/         # ← 自动生成
│   └── pubspec.yaml
│
├── taro_app/                     # 🔷 Taro 端
│   ├── src/
│   │   ├── styles/
│   │   │   └── tokens.scss         # ← 自动生成
│   │   ├── api/
│   │   │   └── generated/          # ← 自动生成
│   │   ├── pages/
│   │   └── components/
│   └── package.json
│
├── docs/                         # 📖 共享文档
│   ├── architecture.md
│   └── design-guidelines.md
│
└── Makefile                      # 🔧 统一构建命令

统一构建命令

# Makefile — 一键操作双端

# 同步 Design Token 到两端
sync-tokens:
	node packages/design-tokens/scripts/gen-dart.js
	node packages/design-tokens/scripts/gen-scss.js
	@echo "✅ Design Tokens synced to both platforms"

# 同步 API 到两端
sync-api:
	cd packages/api-schema && sh scripts/gen-dart.sh
	cd packages/api-schema && sh scripts/gen-ts.sh
	@echo "✅ API Client synced to both platforms"

# 全量同步
sync-all: sync-tokens sync-api

# Flutter 开发
flutter-dev:
	cd flutter_app && flutter run

# Taro 小程序开发（微信）
taro-dev-weapp:
	cd taro_app && npm run dev:weapp

# Taro H5 开发
taro-dev-h5:
	cd taro_app && npm run dev:h5

# 全量构建
build-all:
	cd flutter_app && flutter build apk --release
	cd flutter_app && flutter build ios --release
	cd taro_app && npm run build:weapp
	cd taro_app && npm run build:h5
	@echo "✅ All platforms built successfully"

---

💉 8. 常见踩坑与避坑指南

错误	后果	修复
Token 手动同步	两端颜色/间距不一致，视觉差异	用脚本自动化，CI 检查一致性
API 模型各端手写	字段名不一致，联调反复	OpenAPI 自动生成，单一来源
Flutter 用 WebView 加载小程序页面	性能差，体验割裂	小程序端用 Taro 原生实现
Taro 端硬编码颜色值	Token 更新后不同步	强制使用 SCSS 变量，lint 规则禁止硬编码
两端路由命名不统一	深度链接跳转混乱	共享路由路径常量表
忽略平台差异盲目"统一"	强行统一导致体验怪异	核心流程统一，交互细节允许平台化差异

---

🔮 9. 进阶：CI/CD 双端流水线

代码提交（Git Push）
│
├── 检测变更范围
│   ├── packages/design-tokens/ 变更 → 触发 Token 同步 + 两端构建
│   ├── packages/api-schema/ 变更 → 触发 API 同步 + 两端构建
│   ├── flutter_app/ 变更 → 仅触发 Flutter 构建
│   └── taro_app/ 变更 → 仅触发 Taro 构建
│
├── Flutter 流水线
│   ├── flutter test → flutter build apk → flutter build ios
│   └── 上传到 App Store Connect / Google Play Console
│
└── Taro 流水线
    ├── npm test → npm run build:weapp → npm run build:h5
    ├── 小程序：自动上传到微信开发者平台（miniprogram-ci）
    └── H5：部署到 CDN / Vercel

---

✅ 双栈落地 Checklist

基础设施搭建

• 创建 Monorepo 项目结构
• 初始化共享 Design Token（JSON → Dart + SCSS）
• 定义 OpenAPI Schema，接入自动生成脚本
• 配置 Makefile 统一命令

Flutter 端启动

• 搭建 Flutter 项目（Riverpod 3.x + GoRouter + Freezed）
• 导入自动生成的 Design Token 和 API Client
• 实现首个核心功能模块（如商品列表）
• 配置 iOS / Android 构建流水线

Taro 端启动

• 搭建 Taro 4.x 项目（React + TypeScript + NutUI）
• 导入自动生成的 SCSS Token 和 TypeScript API 类型
• 实现首个核心功能模块（与 Flutter 端对齐）
• 配置微信小程序 / H5 构建流水线

协同验证

• 两端同一页面视觉对比（截图对齐检查）
• 两端同一接口联调验证（数据一致性）
• Token 变更后自动同步验证
• API 变更后两端编译通过验证

上线前

• Flutter App 提交应用商店审核
• 小程序提交平台审核
• H5 部署并验证
• 全平台功能回归测试

---

全平台产品就像交响乐团 — Flutter 是弦乐组，负责深沉有力的主旋律； Taro 是管乐组，负责明亮灵动的伴奏。它们演奏不同的声部， 但遵循同一份乐谱（Design Token + API Schema），才能合奏出和谐的用户体验。 双栈不是妥协，而是精准的分工。