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 无法自由分发）