Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

运行项目

Oak 项目高频使用的脚本，已经从“前台/前后台两套模式”收敛成“目标端开发进程 + 真实后端进程 + 生成类脚本”三类。当前模板里最值得先记住的是下面这些。

1. 生成类脚本

make:domain

npm run make:domain

把当前项目和依赖模块的实体定义编译成 src/oak-app-domain。

当前项目模板应让它读取 ES 构建配置：

oak-cli make:domain --configFile ./tsconfig.es.json

旧项目如果仍缺少这个参数，可先执行 oak-cli migrate:tsconfig --dry-run 检查迁移计划，再执行正式迁移。不要让领域生成和 build:es 分别读取两套 aliases。

依赖模块实体读取顺序是：

  • es/entities
  • lib/entities
  • src/entities

其中 lib/entities 只是历史兼容回退。生产发布包应优先提供 es/entities/*.d.ts 和同名 .js，不要再依赖发布 src。

make:locale

npm run make:locale

把项目和依赖模块中的多语言资源编译成 src/data/i18n.json，并生成兼容入口 src/data/i18n.ts。

当前 i18n.json 承载真实 i18n 行数据，i18n.ts 只是从同目录 JSON 读取并导出。后续 build:lib / build 会把这个相对 JSON 运行时资产复制到输出目录，因此不要只提交或发布其中一个文件。

make:dep

npm run make:dep

根据 src/configuration/dependency.ts 生成初始化、特性装配和运行时类型文件。默认只创建缺失的标准目标，不覆盖已有定制文件；只有显式使用底层 oak-cli make:dependency --rebuild 才会重建。当前普通应用的标准目标主要包括：

  • src/initialize.server.ts
  • src/initializeFeatures.ts
  • src/features/index.ts
  • src/types/RuntimeCxt.ts
  • src/types/DependentExceptions.ts

旧模板里的 src/initialize.frontend.ts 不再是当前纯前台调试入口；新项目不要围绕它做初始化拼接。

project:init

npm run project:init

根据已安装的 oak.business.module 依赖刷新 src/configuration/dependency.ts，并按项目初始化状态新增或增量补齐依赖模板。首次初始化、存在 pending 状态或使用 --force 时会覆盖模板；依赖集合变化后的普通增量模式会保留已有文件，但仍会补回缺失的模板文件。成熟项目如果有意删除或替换过模板文件，应先检查 .oak-project-init.json 状态再执行。

普通应用模板的 postinstall 顺序是：

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

这个顺序保证模板实体先创建，领域代码再根据最终实体生成，最后才生成依赖装配文件。

2. 开发类脚本

dev

npm run dev

当前模板最常用的开发入口。它同时启动：

npm run server:start
npm run start:web

也就是说，dev 不是旧意义上的纯前台模式，而是后端和 web 开发服务一起启动。

start:web

npm run start:web

只启动 web 开发服务。它不再代表“把后端逻辑全部跑在浏览器里”的旧前台模式。

start:mp:<workspace>

npm run start:mp:wechatMp

启动微信小程序开发服务。当前新应用默认只生成 Web；先通过 oak-cli add mp wechatMp 添加默认小程序 workspace，才会获得这组脚本。需要后端时，另开终端运行 server:start。

start:native:<workspace>

npm run start:native:native

启动 React Native 开发服务。当前新应用需要先执行 oak-cli add rn native。实际生成的脚本带 workspace 后缀：

npm run start:native:native
npm run run:android:native
npm run run:ios:native

当前 workspace 还会生成生产构建命令：

npm run build:native:native:android
npm run build:native:native:ios

最后一个 native 是 workspace 名；如果创建时使用 oak-cli add rn mobile，对应后缀就是 mobile。Android 生产构建仍要求本机配置 JDK、Android SDK、ANDROID_HOME 或 native/android/local.properties；iOS 构建要求 macOS 与 Xcode。Metro bundle 成功只能验证 JavaScript、路由和 render 链路，不能代替 APK/IPA 构建。

旧文档里的无 workspace 后缀 run:android、run:ios 和 run:bundle 不是当前模板命令。

Desktop workspace scripts

Desktop 通过 oak-cli add 生成带 workspace 名的脚本。例如：

oak-cli add desktop desktop
npm install
npm run start:desktop:desktop
npm run build:desktop:desktop

Electron workspace：

oak-cli add desktop desktop-electron --runtime electron
npm install
npm run start:desktop:desktop-electron

这些脚本内部调用 oak-cli start/build --target desktop --render tauri|electron --subDir ...。CLI 同时管理 Vite renderer 和原生宿主，不需要另外手工启动 tauri dev 或 Electron main。

clean:cache

npm run clean:cache

清理本地构建缓存，适合在切换目标端或遇到缓存异常时使用。

3. 后端类脚本

build

npm run build

当前模板先通过 prebuild 自动执行 make:locale，随后 build 等价于 build:lib && build:es && copy-config-json。build:lib 生成后端运行需要的 lib 产物；build:es 使用 tsconfig.es.json 做 noEmit 检查，并启用 XML 类型检查、render 注入声明和严格 Less Module 检查。web 和小程序产物使用独立目标命令：

npm run build:web
npm run build:mp

build:bundle

npm run build:bundle

这是新应用模板提供的 opt-in server runtime bundle。它并行执行 TypeScript 检查与 esbuild 后端打包，输出 dist/server.js、dist/package.json、dist/target、dist/configuration、dist/oak-packages 等部署内容。

该能力目前仍是可选发布路径，普通 npm run build / build:lib 不会自动切换到 bundle。使用前应阅读部署，确认数据库驱动、第三方运行依赖和根配置文件都已进入预期位置。

server:init

npm run server:init

仅在首次部署到空数据库时初始化结构与 seed。当前模板通常使用 dropIfNotStatic，会删除并重建所有非 static 表；它不是刷新初始化数据的增量命令。已有开发库或生产库应生成并审核结构升级计划，并用明确的数据迁移更新 seed。

db:upgrade:plan

npm run db:upgrade:plan

对比当前编译后的 lib/oak-app-domain/Storage 和目标数据库，生成结构升级计划。默认输出到 .oak-upgrade/<时间戳>，只写 migration.sql、rollback.sql、summary.json、table-changes.json、warnings.json 和 rename-candidates.json，不会修改数据库。

常用参数是：

npm run db:upgrade:plan -- -o .oak-upgrade/release-20260508
npm run db:upgrade:plan -- --largeTableRowThreshold 500000
npm run db:upgrade:plan -- --execute

--execute 会执行排序后的结构升级 SQL，且不会自动跳过 manualSql。如果计划里有 manualSql、warnings 或 renameCandidates，先人工确认再进入发布执行。

server:start

npm run server:start

启动真正的 Oak 后端运行态。

4. 最常见顺序

日常开发最常见的是：

npm run make:domain
npm run make:dep
npm run dev

需要先起后端再单独起 web 时，可以拆成：

npm run server:start
npm run start:web

需要联调多端时，则通常是：

npm run server:start
npm run start:mp:wechatMp
npm run start:native:native

其中 MP、Native、Desktop 脚本只在对应 workspace 已添加时存在。这里的 wechatMp 和 native 是示例 workspace 名；自定义名称会生成对应后缀，例如 start:mp:mp-admin、start:native:mobile、start:desktop:ops-desktop。

不要再把 start:web、start:mp 理解成旧文档里的“前台模式”。