Vendure CLIbuild命令详解一键编译 Server、Worker 与 Dashboard 的生产构建指南【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendurevendure build是 Vendure CLIvendure/cli中负责生产构建的核心命令它使用 TypeScript 编译器tsc编译服务端Server与 Worker使用 Vite 构建 Dashboard 前端。本文以skills/vendure-cli/commands/build.md为骨架结合 build 命令源码 与其 单元测试完整讲解命令语法、全部选项、tsconfig 解析规则、多进程构建编排原理并给出 CI、Docker、Watch 模式下的可落地实战方案。读完本文你将能够根据项目形态单包或 monorepo正确执行生产构建并能解释--clean、--watch、--no-progress等选项背后的实现机制。命令概述与适用场景Vendure 项目由三部分构成提供 GraphQL API 的Server、处理异步任务的Worker、以及管理后台Dashboard独立前端应用。生产部署前三者都需要编译为可运行的产物Server / WorkerTypeScript 源码经tsc或实验性的原生编译器tsgo编译为 JavaScript输出到 tsconfig 中outDir指定的目录默认dist/Dashboard经 Vite 构建为静态资源默认输出到dist/dashboard见 脚手架 vite.config.hbs 模板 中build.outDir配置。vendure build将这三个构建过程统一编排避免手工拼接多条tsc -p ...与vite build命令时容易踩到的输出目录冲突、进程编排等坑。前提如何调用 CLIvendure/cli通常是项目或工作区的 devDependency。CLI 技能文档 SKILL.md 明确规定不要硬编码npx应根据项目根目录的锁文件选择对应的包管理器 runner根目录锁文件包管理器调用方式bun.lock/bun.lockbbunbunx vendure commandpnpm-lock.yamlpnpmpnpm exec vendure commandyarn.lockyarnyarn vendure commandpackage-lock.jsonnpmnpx vendure command无锁文件npm兜底npx vendure command若vendure/cli全局安装可直接调用vendure command。本文示例沿用 build.md 中的裸vendure …写法实际执行时请按上表加上 runner 前缀。命令语法与构建目标Targetvendure build [target]target为可选参数默认all可选值在源码 build.ts 中定义为export type BuildTarget all | server | worker | dashboard;Target行为all默认依次构建 Server、Worker 与 Dashboard编排顺序见下文server仅按服务端 tsconfig 编译 Serverworker仅按 Worker tsconfig 编译 Workerdashboard仅运行 Vite 构建 Dashboard非法 target 会立即报错退出normalizeBuildTarget对未知值抛出Unknown build target ...build.ts对应测试见 build.spec.ts。选项详解结合源码命令的完整选项声明位于 command-declarations.ts与 build.md 中的表格一一对应选项说明源码行为build.ts--tsconfig pathServer 的 TypeScript 配置Worker 未单独指定时也复用该配置传给tsc -p path默认按候选文件自动发现见下文--worker-tsconfig pathWorker 独立的 TypeScript 配置优先级--worker-tsconfig--tsconfig 自动发现--vite-config pathDashboard 构建使用的 Vite 配置追加vite build --config path--experimental-tsgo服务端/Worker 使用实验性原生 TypeScript 编译器将编译工具从typescript/tsc切换为typescript/native-preview/tsgo--clean构建前删除输出目录对 tsc 侧删除各 tsconfig 的outDir对 Vite 追加--emptyOutDir--watch监听源码变更并增量重建常驻进程三个构建进程均追加--watch--no-progress关闭 spinner/进度渲染日志稳定见下文进度显示逻辑--verbose展示底层构建工具的完整输出默认对 Vite 追加--logLevel warn并捕获输出verbose 时透传全量输出tsconfig 自动发现规则未显式指定--tsconfig/--worker-tsconfig时源码按以下候选顺序查找build.tsconst serverTsConfigCandidates [./tsconfig.server.json, ./tsconfig.build.json, ./tsconfig.json]; const workerTsConfigCandidates [./tsconfig.worker.json, ./tsconfig.build.json, ./tsconfig.json];即优先使用 Server/Worker 专属配置其次tsconfig.build.json最后回退到tsconfig.json。resolveBuildTsConfigs的完整优先级与回退逻辑都有单元测试覆盖build.spec.ts。从脚手架模板tsconfig.template.json看默认服务端 tsconfig 包含outDir: ./dist、emitDecoratorMetadata、experimentalDecorators等 Vendure/NestJS 运行所需的编译选项并通过references引用 tsconfig.dashboard.json 以类型化校验 Dashboard 扩展。编译工具参数Server/Worker 的编译参数固定为-p tsconfig --noEmitOnErrorWatch 时追加--watchbuild.ts即任一文件编译报错都视为构建失败。Dashboard 的 Vite 参数在非 verbose 模式下追加--logLevel warn以保持输出整洁--clean时追加--emptyOutDirbuild.spec.ts 有对应断言。多进程构建编排为什么 Dashboard 先构建vendure build all不是简单地把三个命令同时扔进终端。源码通过getBuildProcessGroupsForTarget将构建过程分组串行执行build.tsDashboard 组先行Vite 在构建启动时会清空其输出目录outDir。若 Dashboard 与 TypeScript 的outDir存在重叠例如都指向dist并行执行会导致 Vite 清空刚刚编译好的服务端产物Server/Worker 组随后当 Server 与 Worker 的 tsconfig 相同时合并为一次tsc编译显示标签server and worker避免重复编译仅当两者配置不同如各自有独立outDir时才拆为两个独立进程build.ts。该顺序保护机制有两处测试佐证builds the dashboard before TypeScript outputs can be emitted to the same directory验证了产物不被覆盖build.spec.tsruns dashboard builds before server output can be emitted验证了分组顺序build.spec.ts。给读者的实操警示如果绕过vendure build手工编排 Vite 与tsc当 Vitebuild.outDir与 TypeScriptoutDir重叠时切勿并行执行否则 Vite 启动时会清空 TS 产物。Watch 模式与--clean的细节--watch用于开发/调试场景的持续增量构建是常驻进程不应在一次性构建中使用。Watch 模式有两个关键行为并行需求Watch 构建必须让各进程同时存活以持续监听因此build all --watch下 CLI 会给 Dashboard 追加--no-emptyOutDirbuild.ts防止 Vite 在每次重建时清空共享输出目录进度关闭Watch 模式自动禁用进度渲染见shouldUseProgress中!options.watch条件。自定义 Watch 脚本时应遵循同样约束要么使用互不重叠的输出目录要么给 Vite 传--no-emptyOutDir。--clean的实现同样谨慎cleanBuildOutputs会先从 tsconfig 解析出outDirgetTsConfigOutDir并对项目目录之外的路径拒绝删除assertSafeCleanPathbuild.ts避免误删非本项目目录共享的outDir会被去重只清理一次build.spec.ts。进度显示与 CI 日志稳定性进度渲染的启用条件在shouldUseProgress中定义build.ts未显式禁用--no-progress或progress: false非 Watch 模式process.stdout.isTTY true交互式终端环境变量CI为空或为字面量false1、true等任何非空非 false 值都会关闭进度。多个构建进程并行时会使用多行 spinner 渲染器createBuildProgressRendererbuild.ts逐个进程显示OK/ERR状态与耗时。因此CI/脚本化构建请使用--no-progress避免 ANSI 控制序列污染日志、保证日志可解析排查构建失败时使用--verbose获取底层工具的完整输出非 verbose 时子进程输出被捕获、失败才回放。退出码与信号处理buildCommand返回进程退出码任一构建进程非零退出时会向其余进程发送SIGTERM停止构建并保留首个失败进程的退出码build.ts测试preserves the first failing target exit code when stopping remaining builds验证了这一行为build.spec.ts。CLI 层随后process.exit(exitCode)command-declarations.ts因此该命令可直接串联进 CI 脚本的失败判断。另外CLI 会为子进程强制设置FORCE_COLOR1除非环境已声明NO_COLOR保证多进程输出带颜色前缀可区分build.ts。实战示例1. 一次构建全部产物默认路径vendure build # 等价于vendure build all等价于依次执行 Dashboard 的 Vite 构建与 Server/Worker 的tsc -p tsconfig --noEmitOnError。2. 仅干净重建 Servervendure build server --clean先删除服务端 tsconfigoutDir指向的目录再执行tsc。适合服务端源码改动频繁、不想动 Dashboard 产物的场景。3. CI 流水线中的稳定日志vendure build --no-progress --verbose--no-progress保证输出不含进度控制字符、可被日志系统逐行解析--verbose在失败时能直接看到 Vite/tsc 的完整报错。4. 自定义 tsconfig / Vite 配置的复杂项目vendure build all \ --tsconfig ./tsconfig.server.json \ --worker-tsconfig ./tsconfig.worker.json \ --vite-config ./config/vite.dashboard.mts适用于 Server 与 Worker 需要不同outDir、或 Dashboard 有自定义 Vite 插件/别名如脚手架模板 vite.config.hbs 中的vendureDashboardPlugin、/gql别名的项目。5. 持续监听式构建vendure build all --watch常驻进程源码变更即增量重建 Server/Worker/Dashboard适合与vendure start配合做本地生产模式验证。注意它不会自动退出切勿在 CI 的检查构建步骤中使用。6. 与 Docker 部署结合构建产物默认输出到dist/服务端/Worker与dist/dashboard前端静态资源。--clean可确保 Docker 镜像层内不残留旧产物部署阶段参考仓库 docker-compose.yml 与脚手架 Dockerfile.hbs 模板 的镜像构建思路编译后用node ./dist/...启动 Server/Worker 入口。生产构建常见问题排查现象原因与对策构建报Could not find TypeScript config file项目根目录缺少tsconfig.server.json/tsconfig.build.json/tsconfig.json之一或--tsconfig路径有误可用--tsconfig ./tsconfig.json显式指定构建报Unknown build target xxxtarget 只能取all/server/worker/dashboardDashboard 产物覆盖了 Server 产物手动并行执行 Vite 与 tsc 且outDir重叠请改用vendure build all已内置 Dashboard 先行分组失败时看不到报错细节默认非 verbose 模式下子进程输出被捕获加--verbose重跑CI 日志出现乱码/进度残留进度渲染依赖 TTY 与 CI 变量显式加--no-progress--experimental-tsgo报找不到工具需额外安装typescript/native-preview依赖源码会给出安装提示build.ts该选项为实验特性生产环境建议保持默认tsc参考与延伸命令参考文档skills/vendure-cli/commands/build.mdCLI 全局技能说明锁文件 runner 检测、非交互环境变量等skills/vendure-cli/SKILL.md构建命令完整实现packages/cli/src/commands/build/build.ts构建命令单元测试含编排顺序、tsconfig 回退、进度开关等 20 余项断言packages/cli/src/commands/build/build.spec.ts命令选项声明packages/cli/src/commands/command-declarations.ts项目脚手架默认 tsconfig 与 Vite 模板tsconfig.template.json、tsconfig.dashboard.json、vite.config.hbs构建完成后可使用vendure start运行已编译的 Server/Worker详见 start.md或用node ./dist/...直接启动入口文件。【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考