快速开始

方式一：使用脚手架（推荐）

VextJS 提供了 vext create 命令，可以快速创建项目骨架：

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

# 创建并指定 Adapter
npx vextjs create my-app --adapter hono

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

# 跳过 npm install
npx vextjs create my-app --skip-install

创建完成后：

cd my-app
npm run dev

访问 http://localhost:3000，你应该能看到 { "code": 0, "data": { "message": "hello world" }, "requestId": "..." } 的 JSON 响应。

方式二：手动创建

1. 初始化项目

mkdir my-app && cd my-app
npm init -y
npm install vextjs

2. 配置 `package.json`

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "start": "vext start",
    "dev": "vext dev",
    "build": "vext build"
  },
  "dependencies": {
    "vextjs": "^0.1.9"
  }
}

Tip

VextJS 要求 "type": "module"，项目使用 ESM 模块格式。

3. 创建目录结构

mkdir -p src/config src/routes src/services

4. 编写配置

// src/config/default.ts
export default {
  port: 3000,
  host: '0.0.0.0',
  logger: {
    level: 'info',
  },
  openapi: {
    enabled: true,
  },
};

如需使用其他 Adapter（如 Hono），先安装对应包再配置：

npm install hono @hono/node-server

// src/config/default.ts
import { honoAdapter } from 'vextjs/adapters/hono';

export default {
  adapter: honoAdapter(),
  port: 3000,
};

5. 编写路由

// src/routes/index.ts
import { defineRoutes } from 'vextjs';

export default defineRoutes((app) => {
  // GET /
  app.get('/', {
    docs: { summary: '首页' },
  }, async (_req, res) => {
    res.json({ message: 'Hello VextJS!' });
  });

  // GET /health
  app.get('/health', {
    docs: { summary: '健康检查' },
  }, async (_req, res) => {
    res.json({
      status: 'ok',
      uptime: process.uptime(),
    });
  });
});

6. 编写服务（可选）

// src/services/example.ts
export default class ExampleService {
  async getGreeting(name: string) {
    return { message: `Hello, ${name}!` };
  }
}

在路由中使用服务：

// src/routes/greet.ts
import { defineRoutes } from 'vextjs';

export default defineRoutes((app) => {
  app.get('/greet/:name', {
    validate: {
      param: { name: 'string!' },
    },
    docs: { summary: '问候接口' },
  }, async (req, res) => {
    const { name } = req.valid('param');
    const result = await app.services.example.getGreeting(name);
    res.json(result);
  });
});

7. 启动

# 开发模式（热重载）
npm run dev

# 生产模式
npm run build
npm start

项目结构

脚手架或手动创建后，你的项目结构应该如下：

my-app/
├── src/
│   ├── config/
│   │   ├── default.ts        # 默认配置
│   │   ├── development.ts    # 开发环境覆盖（可选）
│   │   └── production.ts     # 生产环境覆盖（可选）
│   ├── routes/
│   │   └── index.ts          # 路由定义
│   └── services/
│       └── example.ts        # 服务层
├── package.json
└── tsconfig.json              # TypeScript 配置（TS 项目）

:::info 约定 VextJS 会自动扫描 src/routes/、src/services/、src/config/ 目录，无需手动注册。路由文件名会映射为 URL 前缀：

文件路径	URL 前缀
`src/routes/index.ts`	`/`
`src/routes/users.ts`	`/users`
`src/routes/admin/index.ts`	`/admin`
`src/routes/admin/settings.ts`	`/admin/settings`
:::

访问 OpenAPI 文档

配置中开启 openapi.enabled: true 后，启动项目即可访问：

Scalar 文档: http://localhost:3000/docs
OpenAPI JSON: http://localhost:3000/openapi.json

CLI 命令速览

命令	说明
`vext dev`	开发模式，文件监听 + 热重载
`vext start`	生产模式启动
`vext build`	构建项目（TypeScript → JavaScript）
`vext create <name>`	创建新项目
`vext stop`	停止 Cluster 进程
`vext reload`	滚动重启 Worker
`vext status`	查看 Cluster 运行状态

开发模式热重载

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

层级	触发条件	行为	速度
Tier 1 — 路由热替换	路由文件变更	原子替换请求处理器，零中断	⚡ 毫秒级
Tier 2 — 服务重载	服务 / i18n 文件变更	重建受影响的服务实例	⚡ 毫秒级
Tier 3 — 冷重启	配置 / 插件变更	完整重启进程	🔄 秒级

下一步

了解项目结构约定
学习路由的三段式定义
探索中间件和插件
查看配置选项

#快速开始

#方式一：使用脚手架（推荐）

#方式二：手动创建

#1. 初始化项目

#2. 配置 package.json

#3. 创建目录结构

#4. 编写配置

#5. 编写路由

#6. 编写服务（可选）

#7. 启动

#项目结构

#访问 OpenAPI 文档

#CLI 命令速览

#开发模式热重载

#下一步