麒麒

Flutter + OpenHarmony 构建镜像命名规范

作者：

zhongdaiqi

在

Flutter + OpenHarmony 构建镜像命名规范

用途：Flutter 打包 OpenHarmony/HarmonyOS 应用，同时支持 GitHub Actions 调用与本地 Docker 拉取打包。
免责：本项目为社区开源工具，与华为技术有限公司无任何隶属或合作关系。"OpenHarmony" 为开放原子开源基金会项目名称。

一、总体结构

📦 2 个 GitHub 仓库（必需），不建文档仓库、不建 SDK 镜像仓库。

<your-github-username>/flutter-ohos-builder              # 主仓库（Action + Docker 双入口）
├── action.yml                               # GitHub Actions 入口
├── Dockerfile                               # 镜像定义（Action + 本地共用）
├── entrypoint.sh                           # 容器入口：环境→构建→签名→产出
├── README.md                               # 用法 + 徽章 + 免责声明
└── .github/workflows/
    ├── release.yml                          # tag 触发：多架构镜像推送 + 发布 v1
    └── selftest.yml                        # 拉模板仓库跑 E2E

<your-github-username>/flutter-ohos-app-template        # 示例模板（必需，兼作 E2E 靶）
├── lib/main.dart
├── ohos/                                    # 鸿蒙平台目录
└── pubspec.yaml

核心原则：

  • 一个主仓库，多个 Tag，双入口（Action + 本地 Docker）
  • 模板仓库必需——Action 无法自测，必须由独立消费者跑 E2E
  • 不按版本拆多仓库，版本锁进 Tag

二、命名规范

仓库命名

类型 命名 必需性 说明
主仓库 flutter-ohos-builder ✅ 必需 Action + 本地 Docker 双入口
模板仓库 flutter-ohos-app-template ✅ 必需 示例工程 + E2E 靶子
文档仓库 — ❌ 不建 放主仓库 README + GitHub Pages
SDK 镜像仓库 — ❌ 不建 许可风险，运行时下载+缓存

命名规则

  • 全小写 + 连字符（kebab-case）
  • 用 ohos，不用 harmony / harmonyos（后者是华为商标）
  • 用 builder 而非 action（兼容本地 Docker 用法）
  • 模板仓库用 app-template 而非 builder-template，避免与主仓库混淆

禁用词

action、ci、mirror、harmony、harmonyos、hms

三、Docker 镜像 / Tag 命名

完整格式

flutter<Flutter版本>-ohos-api<API版本>-<架构>

标签体系

Tag 示例 用途 说明
latest 跟随最新稳定版 便捷拉取
v1 / v1.2.3 语义版本 Action 引用用 @v1
flutter3.22.0-ohos-api12-amd64 锁定工具链 生产可复现（Intel/AMD）
flutter3.22.0-ohos-api12-arm64 锁定工具链 Apple Silicon
flutter3.24.0-ohos-api12-amd64 锁定工具链 新版 Flutter

命名细则

  • 全小写，点号用于版本，连字符用于分隔
  • 架构用 amd64 / arm64（Docker buildx 平台标准值 linux/amd64、linux/arm64）；禁用 x64，会导致多架构 manifest 构建失败
  • API 版本用 api12（对应 DevEco 5.0），而非 DevEco 市场版本号 5.0.0——真正影响构建兼容性的是 API level
  • Flutter 版本须标 fork：openharmony-sig 的 flutter_flutter，版本形如 3.22.0-ohos；官方 3.22.0 不支持鸿蒙
  • 一个仓库，CI 矩阵自动产出所有 Tag

四、镜像地址

# GHCR（GitHub Container Registry）
ghcr.io/<your-github-username>/flutter-ohos-builder:latest
ghcr.io/<your-github-username>/flutter-ohos-builder:flutter3.22.0-ohos-api12-amd64

# Action 引用
<your-github-username>/flutter-ohos-builder@v1

⚠️ GHCR / Docker 要求全小写。CI 中 ${{ github.repository_owner }} 若含大写，需先转小写，否则推送报错。

五、两种调用方式

1. GitHub Actions

- name: Build HarmonyOS App
  uses: <your-github-username>/flutter-ohos-builder@v1
  with:
    flutter-version: '3.22.0-ohos'      # 注意：是 openharmony-sig fork 版本
    ohos-api: '12'
    build-mode: 'release'

2. 本地 Docker

docker pull ghcr.io/<your-github-username>/flutter-ohos-builder:flutter3.22.0-ohos-api12-amd64

docker run --rm -v "$PWD":/workspace \
  ghcr.io/<your-github-username>/flutter-ohos-builder:flutter3.22.0-ohos-api12-amd64 \
  flutter build hap --release

⚠️ 不提供"本地裸脚本"入口——鸿蒙 SDK 无法自由下载分发（需华为账号登录 DevEco），本地用户仍需自备 SDK；要免装环境请走 Docker。

六、版本号与 Tag 对应

场景 引用方式 稳定性
跟随稳定版 @v1 或 :latest 随版本迁移
生产可复现 @flutter3.22.0-ohos-api12-amd64 永久锁定
主版本升级 @v2 破坏性变更时新建

七、避坑清单

坑 后果 正确做法
名字带 harmony/harmonyos 商标风险 用 ohos
名字带 action/ci/mirror 误解用途 用 builder
架构用 x64 buildx 构建失败 用 amd64
Tag 用 DevEco 版本号 5.0.0 随 IDE 漂移 用 API level api12
Tag 不标 fork 版本 装到官方 Flutter，构建失败 标 3.22.0-ohos
按版本拆多仓库 维护地狱 一仓库 + 多 Tag
提供本地裸脚本 SDK 无法分发，死路 只保留 Docker 入口
不建模板仓库 Action 无法自测 模板仓库必需
建文档仓库 过度设计 README + Pages
大小写混用 GHCR 报错 全小写

八、README 免责声明（顶部固定）

本项目为社区开源工具，用于 Flutter 构建 OpenHarmony 应用，
与华为技术有限公司无任何隶属或合作关系。
"OpenHarmony" 为开放原子开源基金会项目名称。
"Flutter" 为 Google LLC 商标，本项目仅作为构建工具使用其社区适配版本。

九、最终定稿（可直接抄）

┌──────────────────────────────────────────────────────────────┐
│  仓库名：    flutter-ohos-builder                            │
│  模板仓库：  flutter-ohos-app-template（必需）                │
│  镜像名：    ghcr.io/<your-github-username>/flutter-ohos-builder  │
│  Action：    <your-github-username>/flutter-ohos-builder@v1  │
│  Tag 格式：  flutter<Flutter版本>-ohos-api<API版本>-<架构>    │
│  架构取值：  amd64 / arm64                                    │
│  版本策略：  latest + v1 + 具体工具链组合                     │
│  免责声明：  社区工具，与华为/Google 无隶属关系               │
│  不建：      文档仓库、SDK 镜像仓库、本地裸脚本入口           │
└──────────────────────────────────────────────────────────────┘

一句话记忆：

主仓库 flutter-ohos-builder + 模板 flutter-ohos-app-template，Tag 用 flutter<版本>-ohos-api<API>-<架构>，架构用 amd64/arm64，Action 用 @v1，本地用 :具体Tag，全程避开 harmony/harmonyos 商标。

十、建仓清单

仓库 1：flutter-ohos-builder

项 值
Description GitHub Action to build Flutter apps into OpenHarmony .hap/.app and publish to AppGallery
Visibility Public（Marketplace 硬性要求）
License MIT
Topics flutter openharmony harmonyos github-actions appgallery ci-cd flutter-ohos
Initialize ✅ README、✅ .gitignore（Node）

建完开：Settings → Actions → General → Workflow permissions → Read and write contents

仓库 2：flutter-ohos-app-template

项 值
Description Minimal Flutter app for OpenHarmony, used to test flutter-ohos-builder end to end
Visibility Public
Initialize ✅ README、✅ .gitignore

建完勾：Settings → General → Template repository（让它出现在 "Use this template" 列表）

不建

  • ❌ 文档仓库（用主仓库 README + GitHub Pages）
  • ❌ SDK 镜像仓库（许可风险 + 体积，运行时下载 + actions/cache 缓存）
  • ❌ 本地裸脚本入口（SDK 无法自由分发）

评论

发表回复

更多文章