#CLI 命令

• vext dev：直接从 src/ 加载 .ts 文件，通过 esbuild 即时编译，支持热重载
• vext build：将 src/ 编译到 dist/，生产模式从 dist/ 加载 :::

#vext typegen — 生成声明并执行 service 依赖诊断（experimental）

为 app.services 与插件里的 app.extend() / defineAppExtensions<{ ... }>() 提供 generated 声明，同时执行 tooling-only 的 service 依赖检查。

#用法

vext typegen [options]

#选项

#产物

.vext/types/services.generated.d.ts
.vext/types/app-extensions.generated.d.ts
src/types/generated/index.d.ts
.vext/manifest/services.json

#示例

vext typegen
vext typegen --check
vext typegen --write-manifest
vext typegen --services --root ./examples/hello-world

#适用边界

• typegen 整体仍属于 tooling-only 能力，不会进入 vext start 的 runtime 主路径；
• vext dev 会在 preflight 中自动执行基础 typegen，vext build 也会在可选 typecheck 与编译前刷新 generated 声明和 manifest；
• TypeScript 语义诊断默认在 ready / reload 后异步输出；如果希望像旧行为一样阻塞启动或重载，可使用 --strict-preflight 或 VEXT_DEV_STRICT_PREFLIGHT=1；
• TS 项目优先输出高质量类型，JS 项目允许退化到 import(...).default / unknown，但命令本身仍可用；
• --write-manifest 会把 service 索引、app.extend() / defineAppExtensions<{ ... }>() 聚合结果与服务依赖图摘要写入 .vext/manifest/services.json；
• 更多 generated 声明示例可结合 服务 与 插件 文档查看。

#vext doctor routes — 静态路由诊断（experimental）

扫描 src/routes/ 中的静态路由元数据，输出重复路由、缺失 docs.summary、自动推断 operationId 等诊断，并可将结果落盘到 inspect / manifest 产物中。

#用法

vext doctor <target> [options]

#Targets

#选项

#产物定位

#示例

vext doctor routes
vext doctor routes --write-inspect
vext doctor routes --write-inspect --write-manifest --json

#当前边界

• 当前 route manifest 与 services manifest 仍分层维护，不合并为单一总 manifest；
• docs.operationId 缺失时，doctor 会按 runtime 行为给出 auto-operation-id 信息提示，而不是误报 warning；
• 路由侧仍由 doctor routes --write-manifest 负责；service 侧则由 typegen --write-manifest 负责。

#vext start — 生产模式启动

以生产模式启动项目。TypeScript 项目从 dist/ 目录加载编译后的代码，需要先执行 vext build；如果缺少有效构建产物，命令会直接失败并提示使用 vext build 或开发期改用 vext dev。

#用法

vext start [options]

#选项

#示例

# 先构建，再启动
vext build
vext start

# 指定端口
vext start --port 8080

# 端口冲突时自动切到下一个可用端口
vext start --port-conflict next

# 排查生产 cold-start 阶段耗时
vext start --startup-profile
vext start --startup-profile-json .vext/inspect/start-profile.json

# 加载 production 配置
PORT=8080 NODE_ENV=production vext start

# 加载自定义环境配置（需存在 src/config/sg-sit.ts）
NODE_ENV=sg-sit vext start

#默认命令

当不传任何命令时，vext 默认执行 start：

# 以下两种方式等效
vext
vext start

#Cluster 模式

如果配置中启用了 cluster，vext start 会自动进入 Cluster 模式，由 Master 进程管理多个 Worker 进程：

// src/config/production.ts
export default {
  cluster: {
    enabled: true,
    workers: "auto", // 自动检测 CPU 核数
  },
};

或通过环境变量启用：

VEXT_CLUSTER=1 vext start

#预加载（Preload）自动注入

vext start 和 vext dev 会自动解析两类 preload 来源：

1. 已安装依赖包中声明的 vext.preload
2. 应用项目根目录中的 preload/

在子进程启动前，这些脚本会统一通过 --import 注入。例如 vextjs-opentelemetry 可利用包级 vext.preload 在应用代码加载前自动初始化 OpenTelemetry SDK；应用项目本身也可以直接在根目录 preload/ 中放置脚本做启动前环境桥接。

首期项目级 preload 规则：

• 目录固定为项目根 preload/
• 非递归扫描
• 项目级 preload 先执行，包级 preload 后执行
• .mjs / .js 直接注入
• .ts / .mts 会在启动前编译到 .vext/preload/*.mjs 再注入
• vext dev 下若 preload/ 里的文件发生变化，会触发 cold restart

详见 预加载 (Preload)。

#启动期配置 Provider

如果项目存在 src/config/bootstrap.ts，vext start / vext dev 会在配置 validate / freeze 前执行其中声明的 bootstrap config provider，并将 provider 返回的 patch 合并到最终配置中。优先级为：default < env < local < provider < CLI。

Cluster 模式下，Master 会把本轮 provider patch 传递给 Worker 复用，避免同一启动周期内 Master / Worker 看到不同远程配置。

#package.json 脚本

推荐在跨平台项目中使用 cross-env 设置环境变量：

npm i -D cross-env

{
  "scripts": {
    "build": "vext build",
    "start": "cross-env NODE_ENV=production vext start",
    "start:sg-sit": "cross-env NODE_ENV=sg-sit vext start",
    "start:us-uat": "cross-env NODE_ENV=us-uat vext start"
  }
}

Vext 本身不内置 cross-env；它只是推荐的脚本层兼容工具，用于在 Windows、macOS、Linux 下统一设置 NODE_ENV。

:::tip 环境文件选择 当前 vext start 没有 --config <file> 这样的参数。环境配置文件的选择机制是：

• 读取运行时 NODE_ENV
• 匹配 src/config/{NODE_ENV}.ts（build 后对应 dist/config/{NODE_ENV}.js）

如果你需要 sg-sit.ts、us-uat.ts 这类自定义环境，只需在启动时设置对应的 NODE_ENV。

代码更新后执行 vext build + vext reload，无需停机即可完成版本更新。适合需要高可用性的生产环境。