在 OHPM（OpenHarmony Package Manager）生态中，三方库的版本号严格遵循 语义化版本控制（SemVer 2.0.0） 规范。这套规范旨在通过版本号直观地传达代码的变更类型与兼容性。以下是详细的版本管理规范：

1. 版本号标准格式

标准的版本号格式为 主版本号.次版本号.修订号（即 MAJOR.MINOR.PATCH），且每一位均禁止在前面添加前导零（如 01.0.1 或 1.0.01 均为无效格式）。

• 主版本号（MAJOR）：当开发者进行了不能向下兼容的代码修改（如删除了某个组件、修改了核心接口）时，必须递增主版本号，同时将次版本号和修订号归零。
• 次版本号（MINOR）：当开发者新增了功能且保持向后兼容时，必须递增次版本号，同时将修订号归零。
• 修订号（PATCH）：当开发者仅进行了程序 Bug 或漏洞修复，且保持向后兼容时，须递增修订号。

2. 预发布与构建信息（可选扩展）

除了标准版本号，还支持附加预发布标识和构建信息：

• 先行版本号（PRERELEASE）：用于标识尚未稳定的预发布版本（如测试版、候选版）。格式为在标准版本号后加连字符（如 1.0.0-alpha、1.0.0-beta.10）。当标准版本号相同时，先行版本的优先级小于标准版本（例如 1.0.0-snapshot < 1.0.0）。
• 构建信息（BUILD）：用于记录编译或构建过程中的附加信息（如时间戳）。格式为在版本号后加加号（如 1.0.0+20250415）。构建信息不影响版本比较时的优先级。

3. 版本比较与解析规则

• 逐级比较：比较时优先比较主版本号，其次次版本号，最后修订号（例如 1.1.1 < 1.1.2 < 1.2.0 < 2.0.0）。
• 缺省字段处理：当版本号存在缺省字段时，缺失字段视为 0（例如 1.2 等价于 1.2.0，1 等价于 1.0.0）。
• 开发初始阶段：主版本号为零（0.y.z）的软件处于开发初始阶段，API 不稳定，视为非稳定版本。

4. 依赖范围解析策略

在配置依赖范围（如 >=1.0.0）时，包管理器会按以下逻辑拉取版本：

• 若仓库同时存在先行版本和标准版本，优先安装符合范围的最新标准版本。
• 若仓库中不存在符合范围的标准版本，则会退而安装符合范围的最新先行版本。

一、 自动化发版流水线：standard-version 配置

在鸿蒙工程的根目录下配置自动化发版工具，使其能够精准识别 ArkTS/TypeScript 项目，并自动递增 oh-package.json5 中的版本号。

// package.json (工程根目录下的 Node.js 配置文件)
{
  "name": "my-harmony-project",
  "scripts": {
    // 核心：配置自动化发版脚本
    "release": "standard-version",
    // 预发布版本（如 RC 版）
    "release:rc": "standard-version --prerelease rc",
    // 模拟运行（不修改文件，仅打印将要执行的版本号变更）
    "release:dry": "standard-version --dry-run"
  },
  "devDependencies": {
    "standard-version": "^9.5.0"
  },
  // 配置 standard-version 适配鸿蒙工程
  "standard-version": {
    // 指定要修改版本号的鸿蒙配置文件
    "bumpFiles": [
      {
        "filename": "oh-package.json5",
        "type": "json" 
      }
    ],
    // 忽略自动生成的 changelog 提交，避免死循环
    "skip": {
      "changelog": false
    }
  }
}

二、 依赖范围解析：多环境版本路由配置

在模块级 oh-package.json5 中，利用 SemVer 范围操作符实现不同环境、不同依赖的精细化版本控制。

// entry/oh-package.json5
{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    // 1. 核心底层库：使用 ^ 范围，允许自动拉取次版本的新功能与 Bug 修复
    "@company/core-network": "^2.1.0",
    
    // 2. 高风险 UI 组件：使用 ~ 范围，仅允许修订号升级，锁定次版本
    "@company/ui-kit": "~1.4.2",
    
    // 3. 存在已知 Bug 的库：精确锁定版本，禁止任何自动升级
    "@company/legacy-adapter": "1.2.3",
    
    // 4. 测试环境专属：显式指定预发布标签，拉取最新测试特性
    "@company/test-mock": "1.0.0-beta.2"
  }
}

三、 工程规范：.ohpmignore 敏感数据脱敏

在发布 HAR 包前，必须配置忽略文件，防止将本地调试配置、私钥或未编译的源码打入 .har 包中。

# .ohpmignore 文件配置示例

# 1. 忽略 IDE 与构建产物
.idea/
build/
node_modules/

# 2. 忽略敏感信息与本地环境配置
.env.local
*.pem
*.key

# 3. 忽略测试代码与文档源文件（仅保留编译后的声明文件）
__tests__/
*.test.ets

四、 破坏性变更（Breaking Changes）平滑过渡：废弃标记

当准备将主版本号从 1.x 升级到 2.0.0 时，在 1.9.x 阶段对即将删除的 API 进行废弃标记，通过 IDE 提示下游开发者。

// src/main/ets/network/OldHttpClient.ets

/**
 * @deprecated 此方法将在 2.0.0 版本中移除，请迁移至 NewHttpClient.request()
 */
export function legacyRequest(url: string): string {
  console.warn('Warning: legacyRequest is deprecated and will be removed in v2.0.0');
  // 原有逻辑...
  return '';
}

五、 CI/CD 自动化发版流水线脚本

在 GitLab CI 或 Jenkins 等流水线中，通过环境变量注入敏感凭证，实现从代码合并到 OHPM 上架的全自动闭环。

#!/bin/bash
# ci-publish.sh

# 1. 安全注入凭证（严禁在脚本中硬编码）
echo "Configuring OHPM credentials..."
ohpm config set publish_id $OHPM_PUBLISH_ID
ohpm config set key_path $OHPM_PRIVATE_KEY_PATH

# 2. 安装 Node.js 依赖并执行自动化发版（基于 Conventional Commits）
echo "Running standard-version..."
npm install
npm run release 

# 3. 编译 Release 模式的 HAR 包
echo "Building HAR package..."
hvigorw assembleHap --mode release

# 4. 自动发布到 OHPM 中心仓
HAR_FILE=$(find ./build -name "*.har" | head -n 1)
echo "Publishing $HAR_FILE to OHPM..."
ohpm publish $HAR_FILE

六、 企业级私仓架构：ohpm-repo 核心配置

对于数据隔离要求极高的企业，基于官方 ohpm-repo 搭建私仓时，必须正确配置网络与存储引擎。

# config.yaml (ohpm-repo 核心配置)

# 1. 网络监听：局域网部署必须改为 0.0.0.0
listen: 0.0.0.0:8088

# 2. 外部访问地址：若配置了 Nginx 反向代理，必须填写代理后的公网/内网地址
server: http://harmony-repo.company.com:8088

# 3. 存储引擎：高并发企业环境推荐 MySQL + 本地文件存储组合
db:
  type: mysql
  host: 192.168.1.100
  port: 3306
  user: ohpm_user
  password: $DB_PASSWORD # 支持环境变量读取
  database: ohpm_db

store:
  type: file
  path: /data/ohpm-storage