如何构建只包含所需 trace 类型的 plotly.js 自定义 bundle 以减小加载体积？
【免费下载链接】plotly.jsOpen-source JavaScript charting library behind Plotly and Dash项目地址: https://gitcode.com/GitHub_Trending/pl/plotly.js
当官方发布的完整 bundle 或现成的 partial bundle 都不符合你的页面需求时，plotly.js 提供了npm run custom-bundle脚本，让你在本地构建只包含指定 trace 类型的 bundle 文件，从而减小加载体积。本文以当前仓库（plotly.js 4.0.0）为例，说明如何准备构建环境、指定 trace 列表、生成产物并确认构建结果。
准备 Node 环境并获取源码
自定义 bundle 的构建在 plotly.js 源码目录内进行，官方在 CUSTOM_BUNDLE.md 中给出的 Node/npm 版本要求为：
- plotly.js 2.5 之前：Node 12 / npm 6
- plotly.js 2.5 起：Node 16 / npm 8
- plotly.js 2.35 起：Node 18 / npm 10
- plotly.js 4.0 起：Node 22 / npm 10
package.json 中的engines字段也确认了"node": ">=22.0.0"，当前仓库version为4.0.0，因此 4.x 版本请使用 Node 22 / npm 10。
获取源码（<version>换成你要构建的发布版本号，仓库按 tag 发布）：
git clone --branch <version> https://github.com/plotly/plotly.js.gitCI 场景下可以用git clone --depth 1只拉一个提交以加快速度。如果已经 clone 过，切换版本用：
git fetch git checkout <version>然后进入目录安装依赖（npm i会安装 package.json 中声明的全部依赖）：
cd plotly.js npm i选择要包含的 trace 类型
先确定你的图表实际用到哪些 trace 类型。--traces参数只接受 src/traces/ 目录下的合法 trace 名（如scatter、scattergl、scatter3d、bar、heatmap等）；如果传入非法名称，构建脚本会报错并打印出完整的合法列表，可据此修正：
<name> is not a valid trace! Valid traces are: [...]两条必须知道的限制：
- 不带
--traces时默认包含全部 trace，等同于完整 bundle； scattertrace 会被强制包含在所有 bundle 中且无法移除。官方建议即使如此也应显式写出scatter，因为该行为未来可能改变。
执行 custom-bundle 构建
最短主路径
进入 plotly.js 源码目录后，用--traces指定你要的类型（逗号分隔、不加空格）：
npm run custom-bundle -- --traces scatter,scattergl,scatter3d构建逻辑在 tasks/custom_bundle.mjs：脚本基于lib/index.js生成一个临时的 partial index（见 tasks/partial_bundle.mjs），用 esbuild 打包，产物输出到dist/目录。构建成功时脚本会打印本次使用的完整配置对象（trace 列表、输出文件名、dist 路径），构建失败会抛出错误。
可选参数
按 CUSTOM_BUNDLE.md 的说明：
--strict：尽可能使用 strict 版 trace 实现（strict 实现依赖 regl 生成的 GPU 代码）。注意--strict会生成lib/index-strict-<out>.js作为入口，而默认入口是lib/index-<out>.js；npm run custom-bundle -- --traces scatter,scattergl --strict--out <name>：修改 bundle 文件名，默认为custom。最终文件名为dist/plotly-<out>.min.js（压缩版）或dist/plotly-<out>.js（未压缩版）：npm run custom-bundle -- --out myBundleName--unminified：生成未压缩版本（对应文档中的“禁用压缩”）：npm run custom-bundle -- --unminified
一个组合示例——创建名为myScatters的未压缩 bundle，包含scatter、scattergl、scatter3d：
npm run custom-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d一个实用技巧：如果你只想要某一类图（如金融图），可以参照 tasks/util/constants.js 中partialBundleTraces给出的官方 partial bundle 组合（如finance、gl3d、cartesian）来挑选 trace 列表，而不是从零开始枚举。
验证构建结果
- 检查产物文件：构建完成后，
dist/下应出现plotly-<out>.js与plotly-<out>.min.js，文件头部带有类似plotly.js v4.0.0 (myScatters - minified)的 license header（由 tasks/util/constants.js 的licenseDist生成）。 - 比对体积：将生成的
plotly-<out>.min.js与完整的plotly.min.js（由npm run bundle产生）对比文件大小，确认体积确实减小。 - 确认 trace 列表：运行时脚本打印的配置对象中
traceList字段列出了本次实际包含的 trace（按字母序排列，且必然包含scatter），可据此核对是否与你传入的一致。 - 页面验证：将生成的 bundle 通过
<script>引入你的 HTML 页面后，用你的真实data调Plotly.newPlot，确认页面只渲染你所保留的 trace 类型且不报错。
限制与替代路径
- 构建环境限制：
build/目录下的样式产物（如build/plotcss.js）由npm run preprocess生成；tasks/bundle.mjs 在缺少该文件时会明确提示“Please runnpm run preprocessfirst”。如果构建过程出现类似缺失文件报错，先执行npm run preprocess再重新构建。 scatter无法移除：这是当前脚本的硬编码行为（tasks/custom_bundle.mjs 中将scatter固定写入 trace 列表），文档提示该行为未来可能变化，请显式包含scatter。- strict 选项：
--strict仅对支持 strict 实现的 trace 生效；不支持的类型仍回落到常规实现。 - 不想自己打包时的替代路径：如果你的库本身就是打包工具（webpack/rollup 等），可以直接
import源码中的 partial index（如 lib/index-basic.js 只注册了bar、pie与calendars组件），让打包器自己裁剪，或参考 BUILDING.md 调整默认构建配置。此时不必走custom-bundle流程。 - 官方发布的 npm 包与 CDN bundle 的说明见仓库 dist 目录文档；只有当这些现成分发形式都不满足你的体积或组成要求时，才需要本文的自定义 bundle 流程。
【免费下载链接】plotly.jsOpen-source JavaScript charting library behind Plotly and Dash项目地址: https://gitcode.com/GitHub_Trending/pl/plotly.js
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
