Oak CLI

@xuchangzju/oak-cli 是 Oak 全栈业务框架的命令行工具。它负责把 Oak 项目从创建、依赖初始化、领域代码生成，一直到 Web、微信小程序、React Native、Desktop 和 TypeScript 构建串起来。

它不是通用的 React/Vite 脚手架。Oak CLI 面向使用 Oak 数据域、OakComponent、checker/trigger、业务模块和 Oak 编译器的项目。

能做什么

• 创建项目：生成 Oak 应用或可复用的 Oak 业务模块。
• 管理平台：为现有项目添加 Web、微信小程序、React Native 或 Desktop 工作区。
• 生成代码：生成实体域、依赖组合、locale 和项目初始化文件。
• 编译运行：统一启动和构建 Web、MP、RN、Desktop、TypeScript 目标。
• 升级迁移：生成数据库升级计划，迁移旧项目的 TypeScript 配置和 RuntimeContext。
• 开发期校验：检查 Oak Render 类型、LESS Module、XML/WXML 组件属性和 TypeScript 诊断。

安装

在 Oak 应用或业务模块中安装为开发依赖：

npm install --save-dev @xuchangzju/oak-cli

环境要求：Node.js >=20、npm >=9。Oak 当前支持 TypeScript 5.x 和 6.x，不支持 TypeScript 7.x；项目中的 TypeScript 版本应保持在 <7。

快速开始

创建 Oak 应用

npx oak-cli create my-oak-app
cd my-oak-app
npm install
npm run dev

应用默认生成 Web 工作区。npm run dev 会启动 Oak 后端和 Web 开发服务器；也可以分别运行 npm run server:start 与 npm run start:web。

首次启动前，请根据创建时选择的数据库检查 configuration/mysql.json、configuration/postgres.json 或 configuration/sqlite.json。数据库密码和其他本地凭据不要提交到版本库。

创建 Oak 业务模块

业务模块可以被多个 Oak 应用复用：

npx oak-cli create my-business --module
cd my-business
npm install
npm run make:domain
npm run build

给现有项目添加平台

npx oak-cli add mp mini-program
npx oak-cli add rn native
npx oak-cli add desktop desktop --runtime tauri

可用平台为 web、mp、rn 和 desktop。Desktop 支持 tauri 或 electron。

常用命令

| 命令 | 用途 | | --- | --- | | oak-cli create <name> | 创建 Oak 应用；加 --module 创建业务模块，加 --dev 使用父目录中的本地 Oak 包 | | oak-cli add <platform> [name] | 为现有项目添加平台工作区 | | oak-cli start --target <target> | 启动开发目标：web、mp、rn、desktop 或 tsc | | oak-cli build --target <target> | 构建目标；TypeScript 构建可传 --configFile、--watch 或 --noEmit | | oak-cli make:domain | 根据实体定义生成 Oak domain 元数据 | | oak-cli make:locale | 生成 locale 输出 | | oak-cli make:dependency | 生成依赖组合、RuntimeContext 和 features 文件 | | oak-cli project:init | 根据已安装的 Oak 包初始化依赖模板 | | oak-cli upgrade | 生成或执行数据库 schema 升级计划 | | oak-cli migrate:tsconfig | 把旧项目的根 TypeScript 配置迁移到工作区配置 | | oak-cli migrate <name> | 执行指定的 Oak 源码迁移；支持 --dry-run |

查看某个命令的完整参数：

npx oak-cli <command> --help

依赖变更后的标准流程

添加、升级或移除 Oak 包后，在项目根目录执行：

npm run project:init
npm run make:domain
npm run make:dep
npm run build

实体定义变化至少需要重新执行 make:domain；依赖组合变化需要执行 make:dep。业务模块通常直接使用 make:dep，应用项目则先执行 project:init 同步依赖模板。

TypeScript 构建示例

Oak 项目通常为库和应用分别维护 TypeScript 配置：

oak-cli build --target tsc --configFile tsconfig.lib.json
oak-cli build --target tsc --configFile tsconfig.es.json --noEmit

需要把 Oak Render 推导出的 data、properties、formData 和 methods 写入 render 声明文件时，加上 --emit-injection-types。需要检查 Render 使用的 LESS Module class 时，加上 --check-style-less。

了解源码

下面的内容面向需要维护 Oak CLI 本身的开发者。普通 Oak 项目使用者通常只需要阅读上面的命令和项目流程。

仓库结构

当前仓库按职责分为几类：

• src/ CLI 自身源码，包括命令实现、脚手架逻辑和 server runtime。

• tooling/ CLI 内部使用的构建与生成工具链。 其中： tooling/scripts/ 是内部脚本， tooling/config/ 是构建配置， tooling/plugins/ 是构建插件。

• scaffold/ 所有生成项目相关的资产。 其中： scaffold/base/ 是基础项目模板， scaffold/fragments/ 是生成片段， scaffold/examples/ 是可选示例模板。

• assets/ CLI 运行时依赖的静态资源，目前主要是 socket-admin。

• docs/ 架构、重构和 backlog 文档。

src/ 内部怎么读

如果你已经知道根目录分层，下一步建议直接按下面顺序理解 src/：

• src/index.ts CLI 入口，只做命令注册和 action 绑定。

• src/shared/ CLI 共用基础设施，包括命令参数类型、option builder、参数归一化、路径注册、模板与文件辅助，以及项目侧 compiler 配置类型入口。

• src/commands/ 各 CLI 命令实现，包括 build/run/clean/make*/rename。

• src/create/index.ts 入口现在位于 src/create/index.ts，负责 create / update 主编排。

• src/create/support.ts create 基础支撑：prompt、路径、scaffold、tsconfig。

• src/create/workspace.ts web / wechatMp 配置生成，以及 update 子目录同步。

• src/create/finalize.ts create 收尾：dependency AST、package.json、rename。

• src/createConfig.ts 项目侧 configuration/compiler.js 的兼容导出入口，实际实现位于 src/shared/create-compiler-config.ts。

• src/types/ 对外共享类型定义，目前主要是 CDN 配置类型。

• src/typings/ server runtime 依赖的全局类型声明，目前主要是 polyfill.d.ts。

• src/server/ CLI 内嵌 server runtime。

如果是第一次接手这仓库，建议先看 源码分层说明。 如果接下来准备继续收敛 src/ 的物理目录，可以再看 src/ 下一阶段重组方案。 如果要改构建脚本、webpack/vite/metro 配置或插件，建议直接看 tooling 分层说明。 如果已经确认问题在 tooling/plugins/，建议继续看 plugins 分层说明。 如果要改 CLI 内嵌 server runtime，建议直接看 server 分层说明。

Render 声明类型输出

oak-cli build --target tsc 默认只在编译检查阶段注入 Oak Render 的 props 类型，最终 .d.ts 保持源码原本的声明：未标注的参数为 any，手写类型保持不变。

需要把 index.ts 中推导出的 data、properties、formData 和 methods 合同写入 web.d.ts、web.pc.d.ts 或 render.native.d.ts 时，显式增加：

oak-cli build --target tsc --configFile tsconfig.lib.json --emit-injection-types

生成的声明不会引用或输出 index.__oak_render_* 虚拟合同文件。--disablePropsInject 会完全关闭 Render 类型插件，因此与 --emit-injection-types 同时使用时以前者为准。

Render LESS Module 检查

需要在编译阶段检查标准 Oak Render 中的 CSS Module class 时，显式增加：

oak-cli build --target tsc --configFile tsconfig.es.json --check-style-less

该参数会把 Render 默认导入的 *.less 解析为虚拟 TypeScript module。例如 Styles.container 会获得精确的 container: string 类型，未声明的 Styles.missing 由 TypeScript 报告 TS2339。嵌套 LESS selector 按 JSX 祖先作用域检查：.container2 { .list { .name {} } .btns {} } 在根位置只暴露 container2，list/btns 只在使用 Styles.container2 的元素子树可见，name 还必须进入使用 Styles.list 的子树。进入深层后会合并根 scope 和所有已满足 selector 前缀的 scope，因此后代仍可使用根 class 和父 scope class，但不会获得尚未满足的其他 selector 分支。LESS 的相对 @import、mixin 展开、class 定义位置和首个定义的声明预览复用 Oak CLI 现有 LESS AST/source map。不开启参数时，编译行为保持不变；Vite TypeScript diagnostics 也读取同一开关。

Render 编译链性能回归可运行：

npm run test:performance

该测试创建独立复杂项目，统计关闭注入、默认注入、声明 emit、重复构建、watch 单文件增量编译和声明消费类型检查的样本数、P50、P95 与最大耗时。详细 fixture 和统计口径见 性能测试说明。

相关文档

• 目录重组最终方案
• 目录重组草案
• Issue Backlog
• 源码分层说明
• tooling 分层说明
• plugins 分层说明
• 微信小程序配置
• 性能测试说明
• server 分层说明
• src/ 下一阶段重组方案

包内路径兼容

目录重组后，仓库内部已经迁移到：

• tooling/
• scaffold/
• assets/

为了兼容历史项目，package.json 中保留了旧子路径到新目录的映射：

• @xuchangzju/oak-cli/config/* -> @xuchangzju/oak-cli/tooling/config/*
• @xuchangzju/oak-cli/scripts/* -> @xuchangzju/oak-cli/tooling/scripts/*
• @xuchangzju/oak-cli/plugins/* -> @xuchangzju/oak-cli/tooling/plugins/*

新代码优先使用新的目录语义路径；旧路径保留主要是为了兼容已生成项目。