🔄 版本迁移指南#

本章记录 lhx-kit 各版本间的 breaking change 以及迁移步骤。

一、📋 版本状态#

{
  "components": [
    {"name": "Banner", "props": {...}, "when": {...}}
  ]
}

{
  "$components": [
    {"$name": "Banner", "props": {...}, "$when": {...}}
  ]
}

2.2 offline.config.ts 增加 schemaVersion#

export default defineOfflineConfig({
  enabled: true,
  versions: {prod: '1.0.0'}
});

export default defineOfflineConfig({
  schemaVersion: '2.0.0',   // ← 新增
  enabled: true,
  versions: {prod: '1.0.0'}
});

三、🚢 0.0.0 → 0.1.0（未发布）#

四、🛠️ 迁移工具（规划）#

4.1 lhx-cli upgrade#

规划中的命令。功能：

lhx-cli upgrade
# 1. 读本地 package.json 的 @lhx-kit/* 版本
# 2. 对比最新版
# 3. 显示每个包的 changelog
# 4. 按顺序执行 migration script
# 5. 运行 doctor 验证

4.2 配置迁移脚本#

lhx-cli migrate <target-version>
# 例如：
lhx-cli migrate 0.1.0   # 把 project.config.ts / offline.config.ts 升级到 0.1.0 格式

实现方式：

• 读现有 config（via @lhx-kit/config）
• ts-morph 做 AST 修改
• 生成 backup *.backup.ts
• 应用修改
• 运行 zod.parse 验证

五、🧪 beta 版本使用#

目前所有包版本都是 0.0.0，未发布到 npm。

如果你想在自己的项目里试：

cd lhx-kit
pnpm install
pnpm --filter '@lhx-kit/*' build

# 在你的项目里
pnpm link --global <绝对路径>/lhx-kit/packages/cli

或者：

cd lhx-kit/packages/cli
pnpm pack
# 产出 lhx-kit-cli-0.0.0.tgz

cd <你的项目>
pnpm add file:<绝对路径>/lhx-kit-cli-0.0.0.tgz

六、📚 Semantic Versioning 约定#

lhx-kit 使用 SemVer 2.0.0：

七、🗓️ 弃用周期#

当某个 API 要被移除时：

Version N      : 新 API 引入，旧 API 标记 @deprecated
Version N+1    : 旧 API 仍可用，但有 console.warn
Version N+2    : 旧 API 移除（仅在 MAJOR 版本升级时才会发生）

典型示例（假想）：

0.2.0：createConfiguredPage({schema})  引入，createPage({schema}) 标记 @deprecated
0.3.0：createPage 仍可用，调用时 console.warn("createPage is deprecated...")
1.0.0：createPage 移除

八、📖 Changelog#

九、🤝 向后兼容承诺#

9.1 配置文件#

• project.config.ts 的字段只会新增不会删除（直到 MAJOR 升级）
• 新字段都是 optional，默认值保持原有行为

9.2 CLI 命令#

• 已有命令的核心语义（如 create <name>）不会变
• 新增选项是 opt-in，不传保持原行为

9.3 Runtime API#

• 公开的 setupMobile / createRequest 等签名不会做 breaking change（MINOR 内）
• 内部 @lhx-kit/runtime/cdn-loader 是给插件用的，不保证兼容（标注为 internal）

十、📖 相关资源#

• Semantic Versioning 2.0.0
• Keep a Changelog
• changesets 文档
• FAQ Q17 — 怎么发布到 npm