前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

工欲善其事，必先利其器。在动手适配 secure_application 之前，得先把开发环境搭好。Flutter-OHOS 的环境搭建和标准 Flutter 有些不同，踩过的坑不少，这篇把完整流程和注意事项都记录下来。

如果你之前已经搭建过 Flutter-OHOS 环境，可以跳到第五节看多平台联调的部分，那块内容对插件开发特别有用。

一、DevEco Studio 安装与配置

1.1 版本要求

工具	版本	说明
DevEco Studio	6.0.2 Release	构建版本 6.0.2.640
构建日期	2026年1月19日	确认是最新稳定版
操作系统	Windows 10+ / macOS 12+	推荐 macOS（可同时开发 iOS）

1.2 下载与安装

1. 访问 HarmonyOS 开发者官网
2. 下载对应操作系统的安装包
3. macOS 用户拖拽到 Applications 目录
4. Windows 用户运行安装程序，建议安装到非系统盘

1.3 首次启动配置

# macOS 首次启动可能需要解除安全限制
sudo xattr -r -d com.apple.quarantine /Applications/DevEco-Studio.app

首次启动后需要配置：

• SDK 路径：建议放在用户目录下，如 ~/OpenHarmony/sdk
• Node.js：DevEco Studio 自带，无需额外安装
• ohpm：OpenHarmony 包管理器，随 SDK 一起安装

📌 注意：DevEco Studio 和 Android Studio 可以共存，不会互相干扰。但如果磁盘空间紧张，注意两个 IDE 的 SDK 加起来可能占用 20GB 以上。

1.4 SDK Manager 配置

打开 DevEco Studio → Settings → SDK Manager：

SDK 组件	版本	必装
OpenHarmony SDK	API 20	✅
Build Tools	最新	✅
Previewer	最新	可选
Emulator	最新	可选（但不支持 Window API）

二、Flutter-OHOS SDK 环境搭建

2.1 获取 Flutter-OHOS SDK

# 克隆 Flutter-OHOS SDK
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
 -b dev flutter_ohos

# 进入目录查看版本
cd flutter_flutter
git log -1 --oneline
# 输出类似：abc1234 Flutter 3.35.7-dev

2.2 环境变量配置

# ~/.zshrc 或 ~/.bashrc
export FLUTTER_OHOS_HOME=$HOME/flutter_flutter
export PATH=$FLUTTER_OHOS_HOME/bin:$PATH

# OpenHarmony SDK 路径
export OHOS_SDK_HOME=$HOME/OpenHarmony/sdk
export HOS_SDK_HOME=$OHOS_SDK_HOME

# 让 Flutter 找到 OpenHarmony SDK
export OHOS_BASE_SDK_HOME=$OHOS_SDK_HOME

配置完成后重新加载：

source ~/.zshrc

2.3 验证安装

flutter doctor -v

正常输出应该包含：

[✓] Flutter (Channel dev, 3.35.7-dev)
[✓] OpenHarmony toolchain - develop for OpenHarmony devices
[✓] DevEco Studio (version 6.0.2)

⚠️ 常见问题：如果 flutter doctor 报 OpenHarmony toolchain 缺失，检查 OHOS_SDK_HOME 路径是否正确，以及 SDK 目录下是否有 toolchains 子目录。

2.4 Flutter-OHOS 与标准 Flutter 的共存

很多开发者同时需要标准 Flutter SDK 和 Flutter-OHOS SDK。推荐使用别名切换：

# ~/.zshrc
alias flutter_ohos="$HOME/flutter_ohos/bin/flutter"
alias dart_ohos="$HOME/flutter_ohos/bin/dart"

# 或者用 fvm 管理多版本
# fvm install 3.35.7-dev --ohos

三、设备准备与连接

3.1 设备 ROM 要求

要求	值
ROM 版本	6.0.0.130 SP8
API 版本	API 20
设备类型	手机或平板
开发者模式	已开启
USB 调试	已开启

3.2 开启开发者模式

1. 进入 设置 → 关于手机
2. 连续点击 版本号 7次
3. 返回设置，找到 开发者选项
4. 开启 USB 调试

3.3 hdc 工具使用

hdc（HarmonyOS Device Connector）是 OpenHarmony 的设备连接工具，类似 Android 的 adb：

# 查看已连接设备
hdc list targets

# 查看设备信息
hdc shell getprop hw_sc.build.os.version

# 安装应用
hdc install path/to/app.hap

# 卸载应用
hdc uninstall com.example.app

# 查看实时日志
hdc hilog | grep SecureApplicationPlugin

# 文件传输
hdc file send local_file /data/local/tmp/
hdc file recv /data/local/tmp/remote_file ./

3.4 设备连接问题排查

问题	原因	解决方案
hdc list targets 无输出	驱动未安装	Windows 安装 HiSuite 驱动
设备显示 unauthorized	未授权	设备上点击"允许调试"
连接不稳定	USB 线质量差	换原装数据线
多设备冲突	同时连接多台	用 -t 指定设备

四、创建验证项目

4.1 创建 Flutter-OHOS 项目

flutter create --platforms ohos,android,ios test_secure_app
cd test_secure_app

4.2 添加 secure_application 依赖

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  secure_application:
    path: ../secure_application  # 本地路径引用

4.3 运行到 OpenHarmony 设备

# 确认设备已连接
flutter devices

# 运行到 OpenHarmony 设备
flutter run -d <device_id>

4.4 验证基本功能

import 'package:flutter/material.dart';
import 'package:secure_application/secure_application.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: SecureApplication(
        onNeedUnlock: (controller) async {
          print('需要解锁');
          controller?.authSuccess(unlock: true);
          return null;
        },
        child: SecureGate(
          blurr: 20,
          child: Scaffold(
            appBar: AppBar(title: Text('Secure Test')),
            body: Center(child: Text('受保护的内容')),
          ),
        ),
      ),
    );
  }
}

如果能正常运行并且切后台时看到模糊效果，说明环境搭建成功。

五、多平台联调环境搭建

5.1 为什么需要多平台联调

适配 secure_application 时，经常需要对比不同平台的行为：

• Android 的 FLAG_SECURE 效果是什么样的？
• iOS 的模糊遮罩延迟移除是多少毫秒？
• OpenHarmony 的 setWindowPrivacyMode 和 Android 有什么区别？

同时在多个设备上运行，可以快速发现差异。

5.2 同时运行多个设备

# 终端1：运行到 Android
flutter run -d android_device_id

# 终端2：运行到 OpenHarmony
flutter run -d ohos_device_id

# 终端3：运行到 iOS 模拟器
flutter run -d iPhone_15_Pro

5.3 日志对比

# Android 日志
adb logcat | grep SecureApplication

# OpenHarmony 日志
hdc hilog | grep SecureApplicationPlugin

# iOS 日志（Xcode Console 或 Console.app）

5.4 联调时的注意事项

注意事项	说明
热重载	OpenHarmony 支持 hot reload，但 native 代码修改需要重新编译
断点调试	DevEco Studio 支持 ArkTS 断点，但不能和 Flutter 断点同时用
日志时间戳	不同设备的时间可能不同步，对比日志时注意
网络环境	确保所有设备在同一网络下（如果用无线调试）

六、项目目录结构

6.1 secure_application 完整目录

secure_application/
├── lib/                              # Dart 源码
│   ├── secure_application.dart       # 主 Widget
│   ├── secure_application_controller.dart
│   ├── secure_application_state.dart
│   ├── secure_application_native.dart
│   ├── secure_application_provider.dart
│   ├── secure_application_web.dart
│   └── secure_gate.dart
├── android/                          # Android 原生代码
├── ios/                              # iOS 原生代码
├── ohos/                             # OpenHarmony 原生代码
│   ├── index.ets
│   ├── oh-package.json5
│   ├── build-profile.json5
│   └── src/main/
│       ├── module.json5
│       └── ets/components/plugin/
│           └── SecureApplicationPlugin.ets
├── windows/                          # Windows 原生代码
├── example/                          # 示例应用
├── test/                             # 测试
├── pubspec.yaml                      # 包配置
└── README.md                         # 文档

6.2 开发时主要关注的文件

• Dart 层修改：lib/ 下的所有文件
• OpenHarmony 适配：ohos/src/main/ets/components/plugin/SecureApplicationPlugin.ets
• 配置文件：pubspec.yaml、ohos/oh-package.json5、ohos/src/main/module.json5
• 示例应用：example/lib/main.dart

七、常见环境问题与解决

7.1 问题清单

问题	症状	解决方案
SDK 版本不匹配	编译报错 API not found	更新 OpenHarmony SDK 到 API 20
ohpm 安装失败	依赖下载超时	配置国内镜像源
签名问题	安装到设备失败	DevEco Studio 自动签名配置
Gradle 版本冲突	Android 编译失败	检查 gradle-wrapper.properties
ArkTS 编译错误	类型检查失败	确认 @ohos/flutter_ohos 版本

7.2 ohpm 镜像配置

# 配置华为镜像
ohpm config set registry https://ohpm.openharmony.cn/ohpm/

# 验证配置
ohpm config get registry

7.3 自动签名配置

在 DevEco Studio 中：

1. File → Project Structure → Signing Configs
2. 勾选 Automatically generate signature
3. 登录华为开发者账号
4. 选择证书和 Profile

💡 小技巧：开发阶段用自动签名就够了，发布时再配置正式证书。

总结

本文完成了 secure_application 适配所需的完整开发环境搭建：

1. DevEco Studio 6.0.2：OpenHarmony 的官方 IDE
2. Flutter-OHOS SDK 3.35.7-dev：支持 OpenHarmony 的 Flutter SDK
3. 设备准备：ROM 6.0.0.130 SP8，API 20，开启开发者模式
4. hdc 工具：设备连接、日志查看、应用安装
5. 多平台联调：同时在 Android/iOS/OpenHarmony 上运行对比

下一篇我们深入分析 secure_application 的架构设计——它和大多数 Flutter Plugin 的架构有本质区别。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• DevEco Studio 下载
• Flutter-OHOS SDK
• OpenHarmony SDK 配置指南
• hdc 工具使用指南
• secure_application GitHub
• 开源鸿蒙跨平台社区
• ohpm 包管理器
• Flutter 多平台开发指南

DevEco Studio 6.0.2 开发环境界面