Vendure CLIvendure start生产启动命令完整指南运行已编译的 Server 与 Worker【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendurevendure start是 Vendure CLIvendure/cli中负责以生产模式运行已编译项目的核心命令它不做任何编译只负责把vendure build产出的dist/index.jsServer与dist/index-worker.jsWorker以子进程方式拉起并编排二者同生共死的优雅退出逻辑。读完本文你将掌握start命令的全部目标target与选项option、它与dev/build在项目生命周期中的分工、其进程管理与优雅退出机制在源码层面的实现原理以及在生产环境裁剪开发依赖后绕过 CLI 直接运行编译产物的正确姿势。命令定位start在 Vendure 项目生命周期中的角色Vendure CLI 覆盖了项目从开发到上线的完整生命周期其中与运行直接相关的命令有三个详见 SKILL.md 的命令总览表命令用途运行的是dev开发模式运行 Server Worker Dashboard支持热重载TypeScript 源码经 ts-node / Vitebuild将项目编译为生产产物编译器输出start运行已编译好的生产产物编译后的 JS 入口三者构成一条清晰的流水线dev面向开发迭代build负责产出start面向部署上线。与dev目标含dashboard不同start没有任何编译或源码执行能力——它假定产物已存在因此官方文档明确要求先运行vendure buildstart本身不做任何编译。一个典型的构建启动链式命令如下vendure build vendure startCLI 的完整命令列表可通过vendure --help查看start在 command-declarations.ts 中的注册定义为Start a built Vendure project目标可选all | server | worker默认all。用法与目标target详解vendure start [target]target为可选参数默认值为all取值范围target行为all默认同时启动 Server 与 Worker 两个进程server仅启动 Server 进程worker仅启动 Worker 进程Job Queue 消费者等后台任务目标参数的归一化逻辑在 start.ts 的normalizeStartTarget()中实现(targetArg ?? all).trim()后必须命中[all, server, worker]三个合法值之一否则抛出Unknown start target xxx. Expected one of: all, server, worker错误并以退出码 1 终止。对应的单元测试 start.spec.ts 明确验证了默认值解析为all、三个合法目标均被接受、而dashboard会被拒绝——这正是它与dev/build的关键差异。为什么没有dashboard目标start不存在dashboard目标。原因是Dashboard管理后台前端在build阶段已被编译为静态资源并由 Server 进程直接托管serve。因此启动 Server 即等于同时上线了 Dashboard无需也不可能单独启动它。这是start与dev其目标包含dashboard走 Vite 开发服务器在目标集合上的本质区别部署时不必为此困惑。选项Options说明start仅有两个选项用于覆盖默认的编译产物入口路径选项说明默认值--server-entry path编译后的 Server 入口文件路径./dist/index.js--worker-entry path编译后的 Worker 入口文件路径./dist/index-worker.js默认值在 start.ts 的getStartProcessDefinitions()中硬编码options.serverEntry ?? ./dist/index.js、options.workerEntry ?? ./dist/index-worker.js。如果你通过自定义 tsconfig 或构建脚本改变了产物输出位置例如把编译结果放到了./build/目录则可用vendure start --server-entry ./build/server.js --worker-entry ./build/worker.jsstart.spec.ts 的用例正好验证了这一场景传入自定义入口后子进程的启动参数会被替换为对应路径。若指定的入口文件在项目目录中不存在命令会在启动任何进程之前报错退出Could not find ./dist/index.js. Run this command after building your Vendure server project.该校验逻辑位于validateProjectFiles()start.ts其意图非常明确在build之前运行start会得到友好报错而不是一个启动即崩溃的进程。源码级原理start命令的执行链路理解start的内部实现能帮助你预判它在各种场景下的行为。完整入口是startCommand()start.ts其执行链路为解析 target调用normalizeStartTarget()校验参数合法性。定位项目目录调用resolveVendureProjectDirectory(process.cwd())定义于 dev.ts。该函数先检查当前目录的package.json是否依赖vendure/core若没有则在 monorepo 常见的packages/、apps/、libs/、services/、modules/等目录中向上扫描寻找含有该依赖的包。这意味着在 monorepo 根目录下运行 CLI它也能正确定位到 Vendure 服务包。生成进程定义getStartProcessDefinitions()返回 server/worker 两份StartProcessDefinition各自携带入口参数与专属颜色Server 为蓝色Worker 为青色。按目标筛选getStartProcessesForTarget()决定启动一个还是两个进程——all返回[server, worker]否则只返回对应单个目标start.ts。校验产物文件存在对所有待启动进程逐一执行existsSync检查。启动子进程并等待最终交由waitForChildProcesses()统一管理生命周期。子进程的启动方式与输出前缀进程实际由startProcess()start.ts启动关键细节包括使用spawn(process.execPath, args, { cwd: projectDir, ... })启动——即用当前 Node.js 可执行文件运行编译后的 JS 入口不经过 ts-node 或任何编译器环境变量强制FORCE_COLOR: 1确保子进程输出带颜色当同时启动多个进程all模式时子进程的 stdout/stderr 被以pipe接管并由pipePrefixedOutput()cli-process-utils.ts按行加上[server]/[worker]前缀后转发到 CLI 自身输出。这样两个进程的日志交错出现时你能一眼分辨来自哪个进程单进程模式server或worker则直接inherit标准输入输出日志不加前缀。进程编排与优雅退出graceful shutdownwaitForChildProcesses()cli-process-utils.ts是start all模式下最值得关注的行为官方文档的要点在此均有源码对应任一子进程退出终止其兄弟进程completeChild()中当某个子进程率先退出无论正常还是异常会立即向其余仍在运行的子进程发送SIGTERM并把该退出码作为整个命令的最终退出码。这正是文档所述If either child exits, the CLI terminates the sibling的实现。等待优雅关闭完成CLI 只发送SIGTERM信号然后等待子进程自行完成关闭钩子Vendure 的onApplicationShutdown等后再退出而不是直接强杀。转发 CtrlC / 终止信号CLI 自身监听SIGINT与SIGTERM收到后向所有子进程转发对应信号信号对应的退出码映射SIGINT→ 130SIGTERM→ 143在signalToExitCode()cli-process-utils.ts中定义。这套一损俱损、共同进退的编排保证了部署在容器如 Docker或进程管理器如 systemd中时任一组件崩溃或收到停机信号都能让整套进程干净退出避免出现Server 挂了 Worker 还在跑的半死状态。生产环境部署注意事项官方文档特别提醒了生产环境中的一个常见坑且这一坑在 SKILL.md 中被列为 Agent 与开发者都必须遵守的关键规则vendure/cli默认是开发依赖devDependency。如果生产镜像执行了npm ci --omitdev/pnpm prune --prod之类的依赖裁剪vendure start将不可用。此时有两种正确做法将vendure/cli显式安装为生产依赖npm install vendure/cli --save继续使用vendure start绕过 CLI直接运行编译产物——这也是官方推荐的最轻量方式node ./dist/index.js # 启动 Server node ./dist/index-worker.js # 启动 Worker直接运行入口文件时你失去了 CLI 的多进程编排与优雅退出逻辑因此若需要同时运行两者应自行借助进程管理器如 systemd、PM2、Supervisor或容器编排Docker Compose 多服务来管理。你还可以用vendure doctor --profile production见 doctor 生产检查来诊断生产配置是否就绪。实用示例与常见场景# 1. 构建后立即启动Server Worker最常用 vendure build vendure start # 2. 只启动 Worker例如在单独的工作节点上消费 Job Queue 任务 vendure start worker # 3. 只启动 Server例如在只承担 API 服务的实例上 vendure start server # 4. 使用自定义编译输出目录 vendure start --server-entry ./build/server.js --worker-entry ./build/worker.js # 5. 生产环境精简部署不依赖 CLI直接运行编译产物 node ./dist/index.js node ./dist/index-worker.js常见错误场景对照未先构建就运行报Could not find ./dist/index.js. Run this command after building your Vendure server project.——先执行vendure build即可。传入了非法目标报Unknown start target xxx. Expected one of: all, server, worker——注意dashboard不在其列这是dev/build才有的目标。想要热重载/开发模式start不提供此能力应改用vendure dev。运行方式与长时进程注意事项vendure/cli通常作为项目依赖安装应按项目锁文件匹配的包管理器来调用不要想当然地使用npx规则详见 SKILL.md项目根目录锁文件包管理器调用方式bun.lock/bun.lockbbunbunx vendure startpnpm-lock.yamlpnpmpnpm exec vendure startyarn.lockyarnyarn vendure startpackage-lock.jsonnpmnpx vendure start无锁文件npm兜底npx vendure start最后务必牢记vendure start是长时间运行的守护型进程——启动后不会自行退出会一直占用终端前台。除非用户明确要求不要仅为了检查而运行它确需运行时应优先放到后台执行如nohup、、systemd 服务或容器环境并配合日志重定向避免阻塞终端或随会话关闭而被终止。小结vendure start是连接构建产物与生产运行的最后一道环节它以最朴素的方式直接用 Node 运行编译后的 JS 入口拉起 Server 与 Worker并用一套精心设计的进程编排保证二者的同步启停与优雅退出。理解了它的目标集合、入口覆盖选项、产物校验与进程管理原理你就能在生产部署、容器编排和 Worker 独立扩缩容等场景下做出正确的命令选择——包括在裁剪了开发依赖的镜像里改用node ./dist/index.js直接运行。延伸阅读完整命令总览见 SKILL.mdstart命令的配套编译命令见 build.md开发模式对应命令见 dev.md命令参数注册与帮助文本见 command-declarations.ts。【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考