三行 plotly.express 就能出一张图：悬停看数值、框选缩放、点图例开关序列，比 matplotlib 的静态图体面得多。然后到了要交东西的环节——导师让你贴进 Word，期刊要 300dpi 的图，老板说 html 打不开。
你搜"plotly 导出静态图"，照着教程做。第一篇让你装 orca，报错；第二篇让你用 `kaleido.scopes.plotly`，报错；第三篇的 `fig.write_image()` 倒是不报错了，冷冷地告诉你：没装 Chrome。
别怀疑自己。这不是你菜，是中文互联网上相当一部分导出教程写于 2020 到 2022 年，而 Plotly 的导出栈在那之后彻底重写过。
一条导出链，已经换了三代
我把 PyPI 的发布记录和 GitHub 官方 release notes 对了一遍，Plotly 的静态导出栈大致是三代的命：
第一代是 orca，早期的官方导出引擎，早已废弃、无人维护。教程里只要出现"安装 orca"，可以直接关掉。
第二代是 kaleido 0.x。2020 年起步，API 长这样：`kaleido.scopes.plotly`。它最大的特点是自带一份 Chromium，装完即用，但社区里也一直有偶发卡死的吐槽。这一支的最后一个版本 0.4.2 停在 2024 年 11 月，之后再没更新。
第三代是 kaleido 1.x。2025 年 6 月 19 日，1.0.0 发布，官方 release notes 第一句就是：如果你之前用 v0，代码和环境都得改。GitHub破坏性变化有三个：老 API `kaleido.scopes.plotly` 直接移除；不再内置 Chromium，要求你系统里有 Chrome；想配合 plotly.py 用，plotly 必须 ≥ 6.1.1。
所以结论很简单：三代路径，目前活着的只有 kaleido 1.x 撑起来的 `fig.write_image()`。
2026 年的正确路径，以及一个国内专属的坑
现在导出一张图，代码就两步：
```
pip install -U plotly kaleido
fig.write_image(“fig1.png”, scale=2)
```
看着简单，但这条链路有个硬依赖：Chrome。kaleido v1 导出图片的原理，是开一个无头 Chrome，把你的图当网页渲染出来——机器上没有 Chrome，报错非常直白，我在实测里原样见过：“Kaleido requires Google Chrome to be installed”，提示你运行 `plotly_get_chrome` 安装。GitHub
坑就在这条安装命令上。`plotly_get_chrome` 从 Google 官方源下载完整 Chrome，安装包约 172MB。我在国内服务器上实测：跑了 10 分钟，只下载了 16MB，最后超时失败。而同样一百多 MB 的 Chrome 安装包，换国内 npmmirror 镜像源，4 秒下完。
所以这一步的建议分三种情况：
笔记本上已有 Chrome（大多数人属于这类）：kaleido 会自动找到，什么都不用做；
服务器、纯命令行环境：用系统包管理器装 chromium，或从国内镜像下载 Chrome 的 headless 版本；
公司内网：提前离线部署 Chrome，这一步绕不过去。
另一条容易踩的红线是版本配对。kaleido v1 要求 plotly ≥ 6.1.1。GitHub截至目前（2026 年 8 月下旬），plotly 最新是 7 月 9 日发布的 6.9.0，kaleido 最新是 5 月 4 日发布的 1.3.0，两条线都进入了稳定的更新节奏。PyPIPyPI反过来，如果你的项目锁死在 plotly 5.x，kaleido v1 配不上，只能用 kaleido 0.4.x 老版本。提问之前先跑一句 `pip show plotly kaleido`，能排除一半的问题。
导出跑通之后，还有四个社区今年真实踩过的坑
一、热图导出 PDF，在 Mac 上打开是糊的。plotly 5.9 之后热图改用矢量化渲染，而苹果自带的"预览"在缩放 PDF 里的图像对象时会做插值，热图直接变模糊；同一份文件在 Chrome、Acrobat 里是正常的。知乎这个问题在官方 issue 里挂了许久，目前没有修复，对策只有换阅读器，或者热图干脆导 PNG。
二、导出的 HTML 发给别人，打开一片空白。`write_html` 默认用 CDN 引用 plotly.js，对方网络访问不到就是白页。加上参数 `include_plotlyjs=‘inline’`，把几 MB 的 JS 直接内嵌进文件，体积大点，但保证能打开。有做量化复盘的博主就踩过这个坑，最后改用离线内嵌才解决。
三、期刊要的"300dpi"，本质是道像素算术题。PNG 导出的参数是像素，不是 dpi：dpi = 像素 ÷ 英寸。期刊单栏宽 3.5 英寸、要求 300dpi，那就是 `width=1050`，高度按比例给足，不用纠结找不到 dpi 参数这回事。
四、安装环节也有雷。Windows 上用 conda 装 plotly，有人一路踩出四个连环坑：国内镜像源不稳、repodata 缓存冲突、pip 残留让 conda 误判"已安装"、中断后残留 `~` 开头的临时目录。知乎知乎上有完整的排障实录。原则就一条：同一个环境里，pip 和 conda 别混着装同一个包。
按场景选格式，一张决策表
长期用的话，建议直接把这张表存下来：
论文投稿（Word）：PNG，width 按"栏宽英寸 × 300"算，scale 取 1 到 2；
LaTeX：PDF 或 SVG 矢量，但热图在 Mac 上预览先回头看坑一；
PPT、周报：PNG，scale=2 起步；
网页、交互式附录：`write_html` 加 `include_plotlyjs=‘inline’`；
数据大屏、报表：`to_html` 存成模板再拼页面，小红书上已经有人用这套做整屏展示；交互图加 Dashboard 甚至开始进一些领域的论文标配。小红书小红书
兜底路径，和接下来值得盯的信号
kaleido 在某个环境彻底跑不通时，兜底方案有两个：`fig.show()` 开浏览器手动存图，难看但能交差；或者干脆交付交互式 HTML，静态图作为补充材料。
两个值得持续关注的信号：一是 plotly 出大版本时，先看 release notes 里的 kaleido 兼容说明——这套配对已经断过一次；二是有批量出图需求（几百张）的话，kaleido v1 支持多进程参数 `n`，比老版本快得多。GitHub
最后说个有意思的事。我搜"kaleido"想看看中文社区的讨论，搜出来的大部分是电子书阅读器的 Kaleido3 彩墨屏——导出工具本身的中文资料几乎是空白，教程还大多是过期转载。遇到问题别指望搜索引擎翻出有效答案，直接去官方文档和 GitHub issues。好消息是，看完这篇，你大概率暂时不用翻了。
