#CLI 命令

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

#vext deploy assets — 上传前端静态资源

读取 dist/client/deploy-manifest.json，把前端构建产物中的 JS、CSS、图片、字体和 public/** 资源上传到配置的目标。首期内置 filesystem 与 mock adapter；普通云厂商上传可通过后续自定义 adapter 承接。

#用法

vext deploy assets [options]

vext deploy assets 不支持位置参数。--manifest、--adapter、--target-dir、--prefix、--state-file 等取值参数必须跟随非 option 值，例如 --manifest dist/client/deploy-manifest.json；--manifest --dry-run 会作为缺值错误失败。

#选项

#示例

# 使用配置中的 upload 目标
vext deploy assets

# 只看计划
vext deploy assets --dry-run

# 本次覆盖上传目录和 key 前缀
vext deploy assets --target-dir .deploy/cdn --prefix my-app/v1

第二次执行时，Vext 会读取 frontend.deploy.upload.stateFile，对比每个 uploadKey 的 sha256；内容未变化的资源会跳过，不会重复上传图片、字体或稳定 public 文件。默认 deploy manifest 不包含 index.html 和 source map：HTML 仍由 Vext 服务端渲染，source map 不随 CDN 静态资源发布。

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

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

#用法

vext typegen [options]

vext typegen 不接受位置参数。未知参数会立即失败，并输出可操作的诊断信息。--root / -C 这类取值选项必须跟随非 option 值；--root --json 会被拒绝，不会把 --json 当成路径。

#选项

#产物

.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]

--root / -C 这类取值选项必须跟随非 option 值；--root --json 会被拒绝，不会把 --json 当成路径。

#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 start 不支持位置参数。--port、--host、--config、--port-conflict、--startup-profile-json 等取值参数必须跟随非 option 值。

#选项

#示例

# 先构建，再启动
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 profile 并覆盖端口
vext start --port 8080

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

#默认命令

当不传任何命令时，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 注入。例如 @devcodex/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 < config profile < local < provider < CLI。

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

#package.json 脚本

{
  "scripts": {
    "build": "vext build",
    "start": "vext start",
    "start:sg-sit": "vext start --config sg-sit",
    "start:us-uat": "vext start --config us-uat",
    "deploy:assets:sg-sit": "vext deploy assets --config sg-sit --dry-run"
  }
}

:::tip 配置 profile 选择 vext start、vext build 和 vext deploy assets 默认读取 production profile，vext dev 默认读取 development profile。需要切换到自定义 profile 时：

• CLI 参数：vext start --config sg-sit
• 环境变量：VEXT_CONFIG=sg-sit vext start

profile 名匹配 src/config/{profile}.ts（build 后对应 dist/config/{profile}.js）。 每条命令最多传入一次 --config。start、dev、build 与 deploy assets 遇到重复参数时会直接失败，不会静默采用最后一个值。

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