#构建 (vext build)

vext build 将 TypeScript/JavaScript 源码编译为可部署的 JavaScript 产物，输出到 dist/ 目录。当前版本的 vext build 按 production-target build 设计：它会对用户源码中的 process.env.NODE_ENV 做生产模式静态注入，但运行时实际加载哪个环境配置文件，仍由 vext start 时的 NODE_ENV 决定。基于 esbuild 实现，纯编译阶段速度极快——典型项目（50+ 源文件）的编译时间通常在 1 秒以内。

#快速开始

# 编译生产产物
vext build

# 运行已构建产物（TypeScript 项目需已生成有效 dist/）
NODE_ENV=production vext start

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

#构建前置产物刷新

TypeScript 项目执行 vext build 时，会先刷新开发工具链需要的 generated 与 manifest 产物，再进入可选类型检查和 esbuild 编译：

1. vext typegen 基础刷新：写入 .vext/types/*.generated.d.ts、src/types/generated/index.d.ts 与 .vext/manifest/services.json
2. doctor routes --refresh --write-manifest：重新扫描路由并写入 .vext/manifest/routes.json
3. 如果传入 --typecheck，此时再执行 tsc --noEmit
4. 最后由 esbuild 输出 dist/

这保证新脚手架或刚清理过 .vext/ 的项目，也能在 vext build --typecheck 中先拿到最新 generated 类型，再进入 TypeScript 校验。

#编译策略

#逐文件编译（File-by-File Transform）

vext build 采用逐文件编译模式，而非 bundle 模式——每个源文件独立编译为一个输出文件，保持 src/ 的目录结构映射：

src/                          dist/
├── index.ts            →     ├── index.js        + index.js.map
├── config/                   ├── config/
│   ├── default.ts      →     │   ├── default.js   + default.js.map
│   └── production.ts   →     │   └── production.js + production.js.map
├── routes/                   ├── routes/
│   ├── users.ts        →     │   ├── users.js      + users.js.map
│   └── posts.ts        →     │   └── posts.js      + posts.js.map
├── services/                 ├── services/
│   ├── user.ts         →     │   ├── user.js       + user.js.map
│   └── auth.ts         →     │   └── auth.js       + auth.js.map
├── plugins/                  ├── plugins/
│   └── redis.ts        →     │   └── redis.js      + redis.js.map
├── middlewares/              └── middlewares/
│   └── auth.ts         →         └── auth.js        + auth.js.map
└── models/                   └── models/
    └── user.ts         →         └── user.js        + user.js.map

#为什么不 Bundle？

#编译选项

#CLI 参数

#输出格式

#优化选项

#自动注入

编译时自动注入以下定义：

define: {
  'process.env.NODE_ENV': '"production"'
}

这会让 build 后用户源码中的 process.env.NODE_ENV 分支按 production 语义被静态折叠。

注意，这个注入并不等于“运行时固定加载 config/production.ts”。运行时实际加载哪个配置文件，仍由 vext start 时的 NODE_ENV 决定，例如：

NODE_ENV=sg-sit vext start

会尝试加载：

dist/config/sg-sit.js

因此，当前 vext build 的推荐用法是：

• 用它生成 production-target artifact
• 用 vext start 的 NODE_ENV 选择环境配置文件
• 不要依赖 build 后用户源码中的 process.env.NODE_ENV 条件分支做 sit/uat/prod 切换

如果你希望在 package.json scripts 中跨平台设置 NODE_ENV，推荐使用 cross-env：

{
  "scripts": {
    "start:sg-sit": "cross-env NODE_ENV=sg-sit vext start"
  }
}

#文件扫描规则

#包含的文件

vext build 扫描 src/ 目录下所有匹配以下模式的文件：

**/*.{ts,js,mjs,cjs}

#排除的文件

编译自动排除以下文件（两层排除规则）：

#通用排除（与开发模式共享）

#生产编译额外排除

#Source Map

#外部 Source Map

vext build 生成外部 .js.map 文件（与 vext dev 的 inline source map 不同）：

dist/
├── index.js          # 编译后的 JavaScript
├── index.js.map      # Source Map（映射回 src/index.ts）
├── routes/
│   ├── users.js
│   └── users.js.map
└── ...

#启用 Source Map 支持

在 Node.js 运行时启用 source map，让错误堆栈显示 TypeScript 行号：

NODE_OPTIONS=--enable-source-maps NODE_ENV=production vext start

未启用时的错误堆栈：

Error: Something went wrong
    at UserService.findById (dist/services/user.js:23:11)

启用后的错误堆栈：

Error: Something went wrong
    at UserService.findById (src/services/user.ts:42:11)

#Source Map 用途

#与 DevCompiler 的对比

vext build 和 vext dev 共享相同的 esbuild 基础配置（createBaseEsbuildConfig()），确保开发和生产环境的编译行为一致：

#共享配置

两者共享的 esbuild 配置包括：

• platform: 'node' — Node.js 运行时
• target: 'node20' — 最低支持 Node.js 20.19.0
• format: 'cjs' — CommonJS 输出
• bundle: false — 逐文件编译
• treeShaking: true — 死代码消除
• keepNames: true — 保留函数名
• charset: 'utf8' — UTF-8 编码
• loader — .ts/.js/.json 等文件类型映射

#编译结果

vext build 执行完成后，输出编译报告：

vext build

  ✓ Compiled 42 files in 487ms
  ✓ Output: dist/

  Files:  42 JS + 42 Source Maps
  Errors: 0
  Warnings: 0

#BuildResult 结构

#运行编译产物

# 基本启动
NODE_ENV=production vext start

# 启用 source map（推荐）
NODE_OPTIONS=--enable-source-maps NODE_ENV=production vext start

# 增大内存上限
NODE_OPTIONS="--enable-source-maps --max-old-space-size=4096" NODE_ENV=production vext start

如果 TypeScript 项目缺少 dist/ 或关键构建产物，vext start 会直接失败并提示先执行 vext build。开发期源码启动请使用 vext dev。

通用脚手架项目没有固定的 dist/index.js 启动入口；直接 node dist/index.js 只适用于你自己维护入口文件并显式调用框架启动逻辑的高级场景。

#VEXT_BUILT 标记

通过 vext start 运行有效 dist/ 构建产物时，CLI 会设置 VEXT_BUILT=1 环境变量。这影响：

• 路径解析：src/routes/ → dist/routes/
• 模块加载：从 dist/ 目录加载 routes、services、plugins、middlewares
• Model 加载：MonSQLize 从 dist/models/ 加载 Model 定义

你不需要手动设置这个变量，使用 vext start 时框架会自动处理。

#部署清单

使用 vext build 部署到生产环境的推荐步骤：

# 1. 安装依赖
npm ci

# 2. 编译
npx vext build

# 3. 仅安装生产依赖（可选，用于 Docker 等场景）
npm ci --omit=dev

# 4. 启动
NODE_OPTIONS=--enable-source-maps NODE_ENV=production npx vext start

#Docker 多阶段构建

# 阶段 1: 编译
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY src/ src/
COPY tsconfig.json ./
RUN npx vext build

# 阶段 2: 运行
FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/src ./src
ENV NODE_ENV=production
ENV NODE_OPTIONS=--enable-source-maps
CMD ["npm", "start"]

#.gitignore

确保 dist/ 目录在 .gitignore 中（编译产物不应提交到 Git）：

dist/
.vext/
node_modules/

#故障排查

#编译失败

Error: [vextjs] No source files found in /project/src

确保 src/ 目录存在且包含 .ts 或 .js 文件。

#运行时找不到模块

Error: Cannot find module './routes/users.js'

可能原因：

1. vext build 后没有重新安装依赖（npm ci）
2. 某些文件被排除规则跳过了（检查是否符合排除规则）
3. 使用了动态 import() 引用 .d.ts 文件

#Source Map 不生效

确保启动时通过 NODE_OPTIONS 传入 --enable-source-maps 参数：

# ✅ 正确
NODE_OPTIONS=--enable-source-maps NODE_ENV=production vext start

# ❌ 参数位置错误
vext start --enable-source-maps

#下一步

• 了解 部署与生产环境 的完整部署指南
• 查看 热重载 了解开发模式的编译策略
• 学习 CLI 命令 中 vext build 的完整参数
• 探索 Cluster 多进程 充分利用多核 CPU