tsParticles CLI 构建体系深潜tsparticles/cli-command-build-bundle-rollup 的 Rollup 打包子命令实现与集成解析【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticlestsparticles/cli-command-build-bundle-rollup是 tsParticles 多包仓库 CLI 构建体系中的一个内部命令包它封装了完整的 Rollup 打包流程作为tsparticles/cli-command-build顶层build命令的一个步骤被调度执行。本文以该包的官方说明文档为骨架结合 bundle-rollup.ts、utils.ts 等源码实现讲清这个命令的调用方式、参数语义、配置解析策略与失败处理机制帮助维护者准确理解并复用 tsParticles 的 Rollup 打包链路。1. 包定位为 build 命令提供 Rollup 打包步骤该包的 READMEcli/commands/build-bundle-rollup/README.md将其定义为Internal command package used bytsparticles/cli-command-buildto run Rollup-based bundle steps.即它不是一个面向最终用户独立使用的工具而是被顶层构建命令 cli/commands/build 复用的内部步骤包。从 package.json 可以确认其基本元信息字段值说明nametsparticles/cli-command-build-bundle-rollup包名cli-command-build-*前缀表明其构建子命令身份version4.3.3与仓库内其他工作区包同版本发布typemoduleESM 包maindist/bundle-rollup.js编译产物入口licenseMIT—依赖声明package.json也印证了其职责边界rollup: ^4.62.2—— 实际执行打包的引擎commander: ^15peerDependency—— 命令行参数解析框架tsparticles/rollup-plugin: workspace:*—— tsParticles 自研的 Rollup 配置生成器作为找不到用户配置时的兜底tsparticles/tsconfig、tsparticles/eslint-config、tsparticles/prettier-config、tsparticles/depcruise-config等 workspace 包 —— 构建时复用的工程配置。README 给出的文档级用法只有一条即在工作区根目录通过 Nx 运行该包自身的构建任务pnpm nx run tsparticles/cli-command-build-bundle-rollup:build这条命令执行的是包的buildscript见下节属于构建这个 CLI 包本身与用这个包去构建粒子库是两个层面阅读源码时需注意区分。2. 包自身的构建脚本build 与 build:ci 的差异package.json 中定义的脚本链如下脚本命令链用途buildclear:dist → prettify:src → lint → compile → circular-deps → prettify:readme本地完整构建会修复--fix格式与 lint 问题build:ciclear:dist → prettify:ci:src → lint:ci → compile:ci → prettify:ci:readmeCI 构建只做prettier --check与不带--fix的 lint不修改文件build:ts:cjstsc -p src用 src/tsconfig.json 编译 TypeScript 到distcircular-depsdepcruise src --include-only ^src --validate ...依赖环检查prepackpnpm run buildpnpm publish前自动执行保证发布产物已构建这套清目录 → 格式化 → lint → 编译 → 依赖环检查 → README 格式化的流水线在cli/commands/build-*各子命令包中保持一致--ci与本地模式的唯一区别是只检查、不修复这一语义会一路传递到第 4 节的命令行参数--ci上。3. 命令定义bundle:rollup 子命令与参数语义命令本体在 bundle-rollup.ts 中基于commander定义const bundleRollupCommand new Command(bundle:rollup); bundleRollupCommand.description(Bundle the tsParticles library using Rollup); bundleRollupCommand.option( --ci, Do all build steps for CI, no fixing files, only checking if they are formatted correctly, sets silent to true by default, false, ); bundleRollupCommand.option( -s, --silent boolean, Reduce the amount of output during the build, defaults to false, except when --ci is set, false, );参数与行为细节bundle-rollup.ts#L19-L35--ci布尔默认falseCI 模式开关。描述中明确了副作用——默认把 silent 设为 true源码中对应silent ... || ci即 CI 下自动静默避免日志污染流水线。-s, --silent boolean默认false降低构建过程输出量。由于 commander 对boolean变量解析为字符串源码做了显式归一化const silentOpt opts[silent] as string | boolean, silent silentOpt false ? false : !!silentOpt || ci;即传入字符串false视为关闭静默传入true/true或开启--ci均会静默。工作目录即目标路径basePath process.cwd()命令只接受当前目录为构建根。若路径不存在直接抛出Provided path does not exist。失败语义核心调用bundleRollup(basePath, silent)返回布尔值false时抛出Rollup bundling failed成功则打印Rollup bundling completed successfully!。模块同时导出函数bundleRollup与命令对象bundleRollupCommand两个符号——这正是它能被顶层 build 命令既当子命令、又当函数调用复用见第 5 节的关键。4. 核心实现bundleRollup 的配置解析与产物写入真正的打包逻辑在 utils.ts 的bundleRollup(basePath, silent): Promiseboolean中整体流程为解析配置 → 逐条执行 rollup → 逐个 output 写盘 → 汇总成败。4.1 配置来源的三级解析策略loadRollupConfigutils.ts#L24-L56按优先级查找 Rollup 配置候选配置文件按顺序rollup.config.mjs→rollup.config.js→rollup.config.cjs常量定义为rollupConfigCandidatesutils.ts#L9。命中后通过pathToFileURL做 ESM 动态import取其default导出RollupOptions单配置或配置数组normalizeRollupConfigs统一归一为数组返回。兜底策略三个候选文件都不存在时读取package.json的version缺失时按0.0.0处理调用 tsParticles 自研生成器 loadParticlesBundlereturn loadParticlesBundle({ dir: basePath, version });若连package.json都不存在则抛出No rollup config file found and package.json is missing。这条兜底链的意义在于仓库中绝大多数包如 bundles/basic/rollup.config.js都显式导入了tsparticles/rollup-plugin的配置生成器见第 6 节而兜底路径保证即使某个新包忘了写配置文件构建命令也能用统一的 tsParticles 构建规范生成产物。4.2 执行与输出写入对解析出的每条配置bundleRolluputils.ts#L81-L118执行调用rollup(config)构建模块图从config.output提取输出配置数组为空则直接报错Rollup config is missing output settings——即该命令要求配置必须声明产物位置对每个output执行writeRollupOutpututils.ts#L63-L74output.file或output.dir存在时调用bundleResult.write(output)把产物写到磁盘两者都不存在时退化为bundleResult.generate(output)只在内存中生成而不落盘最后await bundleResult.close()释放资源进入下一条配置。任何一步异常都会被catch捕获console.error(e)后返回false由上层命令转为Rollup bundling failed抛出。静默模式只抑制Rollup bundling started/Rollup bundling completed两条进度日志错误输出不受影响。5. 在顶层 build 命令中的编排位置bundleRollupCommand并非孤立存在。顶层命令 cli/commands/build/src/build.ts 通过buildCommand.addCommand(bundleRollupCommand)将其注册为build的子命令bundle:rollup同时提供快捷 flag-b, --bundle-rollupBundle the library using Rollup。值得注意的两处编排细节all默认行为不对称build命令在未指定任何 flag 时all true其步骤映射为options { circularDeps: all || !!opts[circularDeps], clean: all || !!opts[clean], distfiles: all || !!opts[dist], doBundleRollup: all || !!opts[bundleRollup], // Rollup 打包属于 all 步骤 doBundleWebpack: !!opts[bundleWebpack], // Webpack 打包只在显式传 --bundle-webpack 时执行 ... };即 Rollup 打包是全量构建的默认一环而 Webpack 打包需要显式开启。这与 READMEcli/commands/build/README.md中tsparticles-build --bundle-rollup/tsparticles-build --bundle-webpack的用法示例一致。步骤顺序固定clean → prettify(src) → lint → tsc → circular-deps → bundleWebpack(若开启) → bundleRollup → prettify(README/package.json/package.dist.json) → dist files任一步失败立即throw中断如Rollup bundling failed。Rollup 打包位于 tsc 编译之后是因为 tsParticles 的 Rollup 配置消费的是dist/browser下的编译产物见第 6 节入口规则。全部步骤完成后printDistStatsDiff会对比构建前后的 dist 统计并打印差异产物总大小变化、bundle 大小变化增大时用console.warn高亮提醒、文件数与文件夹数变化——这是仓库层面控制打包体积回归的机制。6. 实战对照bundles/basic 的 Rollup 配置如何被这条命令消费以仓库中一个真实 bundle 包 bundles/basic 为例其配置文件 rollup.config.js 完整展示了用户显式配置分支的形态import { loadParticlesBundle } from tsparticles/rollup-plugin; import { fileURLToPath } from node:url; import fs from fs-extra; import path from node:path; const __filename fileURLToPath(import.meta.url), __dirname path.dirname(__filename), rootPkgPath path.join(__dirname, package.json), pkg await fs.readJson(rootPkgPath), version pkg.version; export default loadParticlesBundle({ moduleName: basic, bundleName: Basic, version, dir: __dirname, progress: false, });当bundleRollup在该包目录执行时恰好命中 4.1 节的第一候选rollup.config.js读取其default导出一个RollupOptions[]由 createParticlesBuild 的bundle分支生成逐条打包。产物命名规则可从 entry.ts 的getEntry得到印证bundle 类构建的入口统一取自./dist/browser/bundle.js或bundle.lazy.js全局变量名按tsparticles${format}.${name}[.lazy][.min]拼装。对照 package.dist.jsontsparticles/basic包的jsdelivr/unpkg字段均指向tsparticles.basic.bundle.min.jsexports同时提供.与./lazy两套类型、browser、esm、cjs 入口——这正是先 tsc 产出dist、再由 Rollup 按多 output 重打包两段式流程的结果。rollup-plugin 的 README 也明确说明输出文件生成在各消费包的dist目录下并支持通过additionalExternals映射额外的外部依赖。7. 小结与适用前提该命令包的全部可观测行为由两个文件定义bundle-rollup.tsbundle:rollup子命令、--ci/-s参数、静默归一化、Rollup bundling failed抛出与 utils.tsrollup.config.mjs|js|cjs三级候选 →tsparticles/rollup-plugin兜底 → 逐配置 rollup →file/dir决定 write 或 generate → 异常返回false。它在 cli/commands/build/src/build.ts 中既是子命令也是-b/--bundle-rollupflag 的执行体默认包含在全量构建中且排在 tsc 之后、dist 文件整理之前。适用前提在 pnpm workspace Nx 工作区内运行包版本以仓库当前4.3.3为准rollup ^4.62.2、commander ^15为其声明依赖脱离该 workspace 直接复用bundleRollup函数时需自行安装rollup并保证目标包具备第 4.1 节所述的配置或package.json结构。【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考