#CLI 命令

VextJS 提供了 vext 命令行工具，覆盖项目创建、开发、构建、部署的完整生命周期。

#安装

vext CLI 随 vextjs 包一起安装，无需额外安装：

npm install vextjs

安装后可以通过以下方式调用：

# 通过 npx
npx vext <command>

# 通过 package.json scripts（推荐）
npm run dev    # → vext dev
npm start      # → vext start
npm run build  # → vext build

#命令概览

#vext create — 创建项目

交互式创建新的 VextJS 项目，自动生成项目骨架和配置文件。

#用法

npx vextjs create <project-name> [options]

#选项

#示例

# 创建 TypeScript 项目（默认 Native Adapter）
npx vextjs create my-app

# 指定 Adapter
npx vextjs create my-app --adapter hono
npx vextjs create my-app --adapter fastify

# 创建 JavaScript 项目
npx vextjs create my-app --js

# 跳过依赖安装
npx vextjs create my-app --skip-install

#生成的目录结构

my-app/
├── src/
│   ├── config/
│   │   ├── default.ts        # 默认配置（port: 3000）
│   │   ├── bootstrap.ts      # 启动期远程配置 provider（可选，按需新增）
│   │   └── production.ts     # 生产环境覆盖（port: 3001）
│   ├── routes/
│   │   └── index.ts          # 示例路由
│   └── services/
│       └── example.ts        # 示例服务
├── package.json
├── tsconfig.json
└── .gitignore

创建完成后：

cd my-app
npm run dev

访问 http://localhost:3000，你应该能看到框架的 JSON 响应。

如需在配置冻结前拉取远程配置（例如 Nacos / 启动期数据库配置），可额外创建 src/config/bootstrap.ts 并通过 defineBootstrapConfig() 注册 provider。该文件不是脚手架强制生成项，但已是框架正式约定路径。

#vext dev — 开发模式

以开发模式启动项目，支持文件监听和智能热重载。

#用法

vext dev [options]

#选项

#端口冲突策略

• error：直接失败（默认）
• prompt：在 TTY 环境下询问父进程如何处理
• kill：尝试终止占用端口的进程
• next：自动选择下一个可用端口

vext dev --port-conflict prompt
vext start --port-conflict next

#生命周期日志分层

默认使用 concise 模式，只保留启动摘要、ready、cold restart / hot reload 结果；如需排障细节，可开启：

vext dev --verbose-lifecycle
VEXT_VERBOSE_LIFECYCLE=1 vext start

#示例

# 使用配置文件中的默认设置
vext dev

# 指定端口
vext dev --port 8080

# 指定地址和端口
vext dev --host 127.0.0.1 --port 8080

# 开启 50ms 防抖（快速连续保存时合并为一次重载）
vext dev --debounce 50

# Docker / NFS 环境使用轮询模式
vext dev --poll --poll-interval 2000

# 禁用 Soft Reload（所有变更均走 Cold Restart）
vext dev --no-hot

#热重载策略

vext dev 提供三层热重载策略，自动选择最优方式：

详见 热重载 章节。

#package.json 脚本

{
  "scripts": {
    "dev": "vext dev"
  }
}

#vext build — 构建项目

将 TypeScript 源码编译为 JavaScript，生成生产可用的 dist/ 目录。

#用法

vext build [options]

#选项

#示例

# 构建项目
vext build

# 构建后启动
vext build && vext start

#构建行为

• 使用 esbuild 进行极速编译（TypeScript → JavaScript）
• 输出目录：dist/
• 保持源码目录结构
• 生成 .js 和 .d.ts 文件

#package.json 脚本

{
  "scripts": {
    "build": "vext build",
    "prepublishOnly": "vext build"
  }
}

vext start [options]

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

# 指定端口
vext start --port 8080

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

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

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

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

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

VEXT_CLUSTER=1 vext start

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 stop — 停止服务

停止正在运行的 Cluster 模式服务。通过读取 PID 文件发送停止信号。

#用法

vext stop [options]

#选项

#示例

# 优雅停止
vext stop

# 强制停止
vext stop --force

# 指定 PID 文件
vext stop --pid-file /var/run/myapp.pid

#vext reload — 滚动重启

触发 Cluster 模式的零停机滚动重启（Rolling Restart）。逐个重启 Worker 进程，确保服务始终可用。

#用法

vext reload [options]

#选项

#示例

# 部署新版本后滚动重启
vext build
vext reload

#滚动重启流程

1. 向 Master 进程发送 SIGUSR2 信号
2. Master 逐个重启 Worker：
   a. 启动新 Worker
   b. 等待新 Worker ready
   c. 优雅关闭旧 Worker
   d. 重复，直到所有 Worker 更新完成
3. 整个过程中始终有 Worker 处理请求，零停机

#vext status — 查看运行状态

查看 Cluster 模式下的服务运行状态，包括 Master 进程和各 Worker 进程的信息。

#用法

vext status [options]

#选项

#示例

vext status

#输出示例

VextJS Cluster Status

Master PID: 12345
Workers: 4/4 running
Uptime: 2d 5h 32m

  PID     State    CPU    Memory    Requests
  12346   online   2.1%   48 MB     125,432
  12347   online   1.8%   52 MB     124,891
  12348   online   2.3%   47 MB     126,003
  12349   online   1.9%   50 MB     125,720

#全局选项

所有命令都支持以下全局选项：

# 查看版本
vext --version
# 输出: vextjs v0.3.2

# 查看帮助
vext --help

#推荐的 package.json 脚本

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "dev": "vext dev",
    "build": "vext build",
    "start": "vext start",
    "stop": "vext stop",
    "reload": "vext reload",
    "status": "vext status",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:cov": "vitest run --coverage",
    "typecheck": "tsc --noEmit"
  }
}

#常见问题

#vext start 报错 "dist/ not found"

需要先执行 vext build 编译 TypeScript 代码。vext start 从 dist/ 加载编译后的 JavaScript 文件。

#开发时应该用 vext dev 还是 vext start？

日常开发使用 vext dev，它直接加载 src/ 下的 TypeScript 文件，支持热重载，无需手动编译。vext start 用于生产环境。

#如何指定 Node.js 版本？

VextJS 要求 Node.js >= 18.0.0。推荐在项目根目录创建 .node-version 或 .nvmrc 文件指定版本：

echo "22" > .node-version

#vext stop / vext reload / vext status 不工作？

这三个命令仅在 Cluster 模式下可用。确保配置中启用了 cluster.enabled: true 或使用了 VEXT_CLUSTER=1 环境变量，且服务通过 vext start 启动。

#下一步

• 了解 热重载 的三层策略细节
• 学习 Cluster 多进程 的完整配置
• 查看 配置 中端口、日志等选项
• 探索 项目结构 的约定