做 uni-app 开发最磨人的场景之一就是：代码在 H5 端好好的，一换到 App 编译打包就翻车。我在一次组件异步化改造里就遇到了这样的报错：H5 本地开发和生产构建都正常，真机预览也没问题，可当我把项目切到 App 端执行打包脚本时，控制台直接抛出一行错误：
[rollup] Invalid value "iife" for option "output.format" - UMD and IIFE output formats are not supported for code-splitting builds第一次看到这个报错，我的第一反应是 App 端某个原生插件冲突，或者页面里有什么 API 在 App 容器里不可用，结果翻遍代码也没找到问题。后来才发现，这根本不是业务代码的语法或运行时报错，而是构建工具在做“输出格式校验”时被卡住了。如果你也正好卡在 uni-app 的 App 编译打包报错上，或者正准备给项目做异步组件、分包优化，这篇文章可以帮你少走不少弯路。
1. 报错现场还原：H5 一切正常，App 打包却卡在 format 上
1.1 报错出现的完整环境和触发方式
这个报错最典型的出现场景是 uni-app 3.x 的 Vue 3 项目。项目一开始走的是标准的页面路由跳转，所有页面组件在 pages.json 里静态注册，编译时所有页面打包进主包，App 端构建历次发布都很顺。某次为了优化首屏，我把一个低频页面改成了异步加载，用 import 函数包裹页面组件，又顺手在 pages.json 里加了一个分包目录。改动后的 H5 端构建一切正常，App 端却开始报错。
代码层面的触发点通常集中在三个地方：
- 项目代码里用了
import('xxx')动态导入； - 某个页面或组件被
defineAsyncComponent包装成异步组件； - pages.json 里配置了
subPackages分包。
这些写法的共同点是会让 Rollup 认为当前构建存在“代码分割（code-splitting）”需求，也就是需要把产物拆成多个 chunk，按需加载。而 App 端构建又偏偏把输出格式限定为 iife 或 umd，两种需求同时出现，Rollup 就直接罢工了。
1.2 报错发生在构建的哪个阶段
这个报错不是发生在代码语法检查阶段，也不是运行阶段，而是发生在 Rollup 生成最终产物之前的“配置校验”阶段。Rollup 在开始打包前会先检查打包输出配置（output）里的各项参数，其中 format 字段决定产物用什么模块规范。一旦发现 format 是 iife 或 umd，同时又存在需要代码分割的多 chunk 构建，Rollup 就会用这个错误信息拒绝继续执行。
理解这一点很重要，因为它决定了排查方向。我见过不少人在看到这个报错后，先去检查某个页面里是不是调用了不兼容的 API，或者怀疑某个原生插件版本过低，折腾半天发现方向完全错了。看到output.format这类字眼，第一反应应该是“构建配置和代码组织方式冲突”，而不是业务代码有问题。
1.3 大多数人会踩的三个误判
结合我自己和团队里其他同事的经验，遇到这个报错时，最常见的三个误判依次是：
- 以为是 App 端原生插件或 SDK 的兼容性问题；
- 以为是某个第三方组件库在 App 环境不可用；
- 以为是云打包服务或本机缓存导致的临时故障。
这三个方向可能引发不同的报错，但正常情况下不会出现output.format这种构建配置词汇。只要报错信息里带上了 Rollup 的 option 校验提示，基本可以确定问题出在构建链路的配置层面，和页面里的业务代码没有直接关系。省下乱猜的时间，尽早进入定位步骤，才是最快的解决路径。
2. Rollup 的 output.format 校验到底在检查什么
2.1 一句话搞懂 output.format 是什么
构建工具的“输出格式”，决定了最终产物用哪种方式暴露给外部环境。Rollup 支持多种格式，最常用的几种可以看这张表：
| 格式 | 全称/含义 | 适合环境 |
|---|---|---|
| amd | 异步模块定义 | 浏览器 + RequireJS 等模块加载器 |
| cjs | CommonJS | Node.js 环境，使用 require 导入 |
| es / esm | ES Module | 现代浏览器原生支持，适合 Web 场景 |
| iife | 立即执行函数表达式 | 直接通过 script 标签引入，无模块系统 |
| umd | 通用模块定义 | 兼容 AMD、CommonJS、全局变量 |
| system | SystemJS 格式 | SystemJS 加载器 |
H5 端构建时，Vite 默认走的是 es（ES Module）格式，浏览器原生支持模块加载，所以动态 import 和分包可以被优雅地拆成多个文件按需请求。App 端就不同了，uni-app 的 App 产物要交给原生容器里的渲染层和逻辑层执行，这些容器没有一个“模块加载器”能替你按需拉取 chunk，框架只能把最终产物打成一大坨自包含的脚本，最常见的格式就是 iife 或 umd。
2.2 为什么 iife/umd 不能和代码分割共存
这是整个问题的核心。
iife 格式的产物是一个自执行的函数体，所有变量都挂在同一个作用域里，文件之间无法通过 import 语句互相引用。umd 虽然借用了一套兼容层，但也要求最终产物在单文件内把 AMD、CommonJS、全局变量三种方案都覆盖到，同样不具备跨文件按需加载的能力。
而代码分割恰恰需要多个 chunk 文件，且这些 chunk 之间必须通过模块语法来建立依赖关系。一个 chunk 要引用另一个 chunk 里导出的变量，在 iife 和 umd 的产物结构里根本没有办法表达。Rollup 在配置校验阶段就会识别到这种矛盾，于是直接给出UMD and IIFE output formats are not supported for code-splitting builds的提示。
2.3 一个比较容易理解的类比
可以把 iife/umd 想象成“必须整体搬进门的一件大家具”。这件家具不允许拆成多个部件分别搬运，因为房门入口就没有给你二次组装的条件。而代码分割就是“需要把家具拆成若干箱子分批次搬进去”的搬运方案。两个方案放在同一套流程里，自然冲突。
H5 端的场景是：房子门口有完整的组装工具（浏览器原生 ESM 加载器），拆成多少箱都能按需搬入并自动组装。App 端的场景是：门口没有组装工具（原生容器不提供模块加载能力），只能整体塞进去。当你既要求整体搬入，又要求拆箱分运，构建系统只能报错停摆。
2.4 “Invalid value”这句话的准确解读
报错开头写着Invalid value "iife" for option "output.format"，看起来像是说 iife 这个值本身不合法，实际上不是。iife 是合法的 format 值，只不过它不能用于当前这种“需要代码分割”的构建场景。Rollup 在配置校验阶段发现 format 与构建目标冲突，就用“Invalid value”来概括。
所以，看到这句话不要急着怀疑框架把格式写错了，而是要追问两件事：到底是谁把 format 设置成了 iife？到底哪段代码触发了代码分割？把这两个问题定位清楚，问题就解决了一大半。
3. 排查链路：从报错关键词反查出真正的元凶
3.1 先拉完整堆栈，不要靠猜
遇到这种构建报错，第一步不是改代码，而是把完整报错堆栈拉出来。如果用的是 HBuilderX 图形界面，报错信息可能被折叠或简化，建议改用命令行执行构建脚本，这样能看到完整的 Rollup 堆栈，通常能直接定位到抛错文件。
uni-app 项目一般在 package.json 里预设了构建命令，类似：
npm run build:app如果项目是基于 CLI 创建，也可以尝试带上调试日志：
DEBUG=vite:* npm run build:app这条命令会输出 Vite 各阶段的大量日志，包括最终注入的 config，对定位配置来源很有帮助。看到堆栈尾部指向node_modules/rollup或者某个编译器插件路径时，就可以进入下一步了。
3.2 确认到底是谁把 format 设置成了 iife
我建议在 vite.config.js 里临时加一个调试插件，在 Rollup 拿到最终配置之前把输出配置打印出来：
import { defineConfig } from 'vite' import uni from '@dcloudio/vite-plugin-uni' function debugConfig() { return { name: 'debug-config', configResolved(config) { console.log('ROLLUP OUTPUT:', JSON.stringify(config.build?.rollupOptions?.output, null, 2)) }, } } export default defineConfig({ plugins: [uni(), debugConfig()], })如果打印出来的对象里有format: 'iife'，说明是某个环节显式设置了这个值。如果没有，那 format 可能是更后面的插件动态注入的。此时可以换一个思路，直接在当前项目依赖里搜索硬编码的位置：
grep -r "format.*iife" node_modules/@dcloudio node_modules/vite这条命令在 macOS 或 Linux 终端下可以快速找出编译器源码里所有把 format 写成 iife 的地方。Windows 环境下可以用文件搜索工具代替。找到位置后，就能理解 App 端构建链路为什么一定要用 iife，以及它在什么条件下会触发报错。
3.3 再定位代码分割的触发点
定位完 format 来源，下一步就是找出触发代码分割的代码。按频率排序，优先级最高的是这三类：
- 动态导入：搜索代码里的
import(关键词； - 异步组件：搜索
defineAsyncComponent或AsyncComponent； - 分包配置：检查 pages.json 里是否有
subPackages字段。
可以用二分法来做快速验证。先把 pages.json 里的分包字段注释掉，同时把最近改动过的异步组件改回静态导入，重新跑 App 构建。如果报错消失，说明触发源基本就在这些位置。随后再逐一把改动恢复，每恢复一项就跑一次构建，很快就能定位到具体是哪一处写的动态加载引发的冲突。
3.4 一个容易被忽略的情况：第三方依赖内部多入口
还有一种情况，代码里没有任何动态导入，分包配置也正常，但报错依然出现。这时候要怀疑第三方依赖本身。某些发布到 npm 的包内部可能包含多个入口文件，或者内部用了动态 import 做按需加载，当 Rollup 对这些依赖做 tree-shaking 和 chunk 合并时，同样可能认定存在代码分割需求。
可以通过报错堆栈中出现的包名路径来判断。如果堆栈里指向node_modules中某个具体依赖，试着在vite.config.js里用resolve.dedupe或optimizeDeps调整对该包的解析方式，再验证是否仍然报错。
为了帮助回顾，我把常见的根因和定位手段整理成一张表：
| 根因类型 | 报错特征 | 定位手段 |
|---|---|---|
| 项目代码动态 import | 报错不指向具体业务文件 | 搜索import(和defineAsyncComponent |
| pages.json 分包配置 | 报错在分包相关的构建阶段 | 注释 subPackages 后重新编译 |
| 编译器插件硬编码 iife | 报错指向 node_modules 内插件 | grep 搜索format.*iife |
| 第三方依赖内部多入口 | 堆栈指向具体 npm 包 | 查看依赖源码 exports 字段 |
| Vite/编译器版本错配 | 配置校验行为异常 | 用 npm ls 确认版本匹配情况 |
4. H5 与 App 两套构建链路的差异，才是这类报错的土壤
4.1 H5 端为什么风平浪静
H5 端本质是标准 Web 构建，Vite 默认的 output.format 是 es，产物是浏览器原生支持的 ES Module。现代浏览器可以直接加载<script type="module">，也支持按需拉取拆分后的 chunk。所以动态 import、分包在 H5 端都是“合法操作”，Rollup 不会遇到格式冲突。
另外，Vite 开发模式下用的是 esbuild 做模块转换，连 Rollup 都没跑起来，自然看不见这个报错。生产构建时虽然走 Rollup，但由于 format 是 es，代码分割完全被允许。这就是为什么同样的代码，H5 端从开发到上线都一路绿灯，App 端却会在打包环节突然卡住。
4.2 App 端为什么要用 iife/umd
uni-app 的 App 端产物要交给原生容器中的渲染层和逻辑层执行。这些容器不是完整浏览器，没有模块加载器能替你按需 import chunk。框架层面把输出格式固定为 iife 或 umd，是为了让最终脚本以“塞进去就能跑”的形态存在。
这个设计本身没有问题，问题在于当你引入异步组件或分包配置后，代码组织方式产生了拆分 chunk 的需求，但输出格式又不允许拆分。两个诉求撞在一起，Rollup 只能选择报错。
不要觉得这是 uni-app 独有的问题，几乎所有面向小程序/App 容器做编译的框架都会面临类似的取舍。在 Web 端天经地义的“按需加载”，到了这类容器环境里就变成了一种需要额外处理的模式。
4.3 分包和异步组件在 App 端的真实处境
App 端本身也有分包概念，但分包机制和 Rollup 的代码分割是两套东西。pages.json 里的 subPackages 是业务层面的页面分包，运行时由框架统一调度；Rollup 的代码分割是构建产物层面的 chunk 拆分。编译器在处理 subPackages 时，为了保护 App 端容器限制，可能会把某些子包的内容做合并，但如果某个子包内存在动态导入或者异步组件，编译器同一条链路上就可能出现“既要 iife，又要拆 chunk”的矛盾。
不同编译器版本对这个问题的处理还不完全一致，所以会出现同一种分包写法有的人能编过，有的人就报错的情况。这也是为什么遇到这类报错，首先要看版本配套。
4.4 版本错配是“昨天还能编，今天就报错”的根源
uni-app 3.x 对 Vite 版本有明确的协同关系。npm 安装依赖时，如果不加约束，很容易把一个关键包升级到编译器尚未适配的版本。Rollup 的格式校验逻辑在不同版本里有差别，原本能通过的组合在新版本下可能直接被拒绝。
检查版本最直接的方式：
npm ls vite rollup @dcloudio/vite-plugin-uni执行这条命令可以列出项目当前实际安装的版本。如果某个包出现多个版本，或者版本号和项目初始安装时不一致，那就很可能是版本错配引发了编译链路的兼容问题。这类问题在 H5 端可能没有明显表现，因为 Web 的构建宽容度更高，而 App 端因为格式限制严格，版本差异直接体现在报错上。
5. 从绕过到根治：三层解决方案按需选用
5.1 方案一：快速止血，把动态 import 改回静态导入
如果你当前最重要的是赶紧出一版安装包，可以先做止血处理。方法很直接：把触发代码分割的异步组件或动态 import 改为静态导入。
// 修改前（动态导入，触发代码分割） const OrderPage = () => import('@/pages/order/detail.vue') // 修改后（静态导入，简单粗暴） import OrderPage from '@/pages/order/detail.vue'副作用很清楚：页面会直接打入主包，主包体积变大。低频页面也会在启动时就被加载，首屏时间可能变差。所以这个方案只适合临时验证，不建议长期保留。
如果那个页面组件体积不大，静态导入的成本可能还可以接受；但要是项目里大量页面都这样处理，App 首屏加载会有明显劣化。记住它的定位：它是止血手段，不是治疗方案。
5.2 方案二：版本对齐，解决编译器与 Vite 不匹配
如果报错是在某次依赖升级之后开始出现的，优先考虑版本对齐。这是接近根因的解法。
操作步骤：
- 先看一下 git 历史或 package-lock.json，找到之前能正常打包时的版本组合；
- 执行
npm ls查看当前实际安装版本； - 查一下当前 uni-app 编译器版本对应的 Vite 版本区间，把 vite 和 rollup 锁定到匹配版本；
- 备份 package.json 和锁文件后执行精准安装，比如
npm install -D vite@x.y.z； - 删除 node_modules 重新安装，彻底清掉旧版本残留；
- 重新构建 App 端验证。
这里有一个经验之谈：升级依赖这种事，真的不适合在发布前夕顺手做。升级前最好先在小分支上验证两端构建，确认没有兼容性问题再合入主干。
5.3 方案三：显式调整 rollupOptions，保留异步加载能力
如果你确认自己的代码结构需要保留异步组件和分包，可以尝试在 vite.config.js 中显式控制 output 行为：
import { defineConfig } from 'vite' import uni from '@dcloudio/vite-plugin-uni' export default defineConfig({ plugins: [uni()], build: { rollupOptions: { output: { // 把动态导入合并进主包，不产生拆分 chunk inlineDynamicImports: true, }, }, }, })inlineDynamicImports: true的原理很简单：告诉 Rollup 把所有动态导入的内容合并回同一个 bundle，不生成拆分 chunk。这样一来 code-splitting 的前提条件不存在，iife/umd 格式的限制自然就被绕开了。
这个方案的适用面是：动态 import 不多、懒加载收益有限的项目，可以长期使用。如果项目里动态 import 很多，或者分包目录体积很大，这会让主包显著膨胀，反而得不偿失。
另一个思路是通过manualChunks把容易冲突的依赖合并：
build: { rollupOptions: { output: { manualChunks(id) { if (id.includes('node_modules')) return 'vendor' }, }, }, }把公共依赖合并成一个 chunk，可以减少多 chunk 之间的互相引用，从而降低冲突概率。但这种方式在 uni-app 项目里需要反复试验，不一定一次就能调到理想状态，要有耐心。
5.4 方案四：依赖排除和 external（谨慎使用）
如果报错明确指向某个第三方依赖，可以尝试把它加入 optimizeDeps 的 exclude 或 external。但这个方案在 uni-app 项目里优先级最低，因为 App 容器的运行环境可能没有对应的全局变量，强行 external 后运行时很可能直接报xx is not defined。
我把几个方案的适用场景和代价整理成一张表，方便对照决策：
| 方案 | 适用场景 | 主要代价 | 建议优先级 |
|---|---|---|---|
| 静态导入 | 临时出包、验证问题 | 主包变大、首屏变慢 | 临时使用 |
| 版本对齐 | 依赖升级后开始报错 | 需要重新安装依赖 | 推荐优先 |
| inlineDynamicImports | 异步代码少、体积可控 | 失去部分懒加载收益 | 按实际情况选择 |
| manualChunks | 公共依赖冲突 | 配置调试成本高 | 视情况使用 |
| external/exclude | 特定依赖引发冲突 | 运行时风险较高 | 最后尝试 |
6. 类似 format 报错的通用排查思路，以及我的一些建议
6.1 你可能遇到的其他 format 报错变体
除了Invalid value "iife" for option "output.format"之外，Rollup 的 format 校验还可能出现其他形态的提示，比如Invalid value 'es' for option 'output.format'，或者直接提示某个格式不支持 code-splitting。
它们的共同点是一样的：format 设置和代码分割存在矛盾。排查思路也一脉相承——先看谁设置的 format，再看谁触发了代码分割。在 uni-app 生态里，最容易触发这个矛盾的就是 App 端默认的 iife/umd 格式配合动态加载。遇到 format 报错，优先怀疑“异步加载”和“分包”这两个方向，基本不会跑偏。
6.2 一个可以复用的排查公式
把这次排查过程抽象成一个固定流程，以后遇到同类问题可以直接套用：
- 判断报错阶段：是否是 Rollup 构建时的配置校验；
- 找到 format 设置者：自定义配置、编译器插件源码；
- 找到 code-splitting 触发点：动态 import、defineAsyncComponent、subPackages、第三方依赖多入口；
- 检查版本匹配度：用 npm ls 看关键依赖的版本关系；
- 选择处理方案：静态导入（临时）/ 版本对齐（推荐）/ output 调整 / external（最后）。
每次排查都记录一下报错关键词和最终原因，积累几次之后，再遇到类似报错基本可以直接照着清单走。
6.3 保持项目健康的两个习惯
第一个习惯是别把锁文件丢在一边。package-lock.json 或 yarn.lock 要提交进仓库，团队成员的依赖版本保持一致，不在发布前一天随手升级 vite 相关包。第二个习惯是在提交前同时跑一遍 H5 和 App 的构建脚本，可以在 package.json 里预制一个检查命令：
{ "scripts": { "check:build": "npm run build:h5 && npm run build:app" } }很多配置类错误等到发版时才发现，往往会直接影响交付节奏。提前把两端构建链路的差异暴露在开发阶段，format 这类问题就能被拦截在提交前。
6.4 最后一点个人体会
拿我自己来说，那次报错最终锁定在 pages.json 新加的一个分包目录，叠加异步组件双重触发。我先把分包保留，异步组件改成静态导入，App 端立刻通过。后来又把 Vite 版本对齐到编译器要求的版本，再改回异步组件，这次就能正常打出带异步 chunk 的包了。
从那以后我养成了一个习惯：每次调整异步组件或分包，都会优先在 App 端编译脚本上验证，而不是只在浏览器里看效果。这两套构建链路的脾气确实不一样，很多坑早踩晚踩都是要踩的，提前在本地踩一遍，总比发版时才发现要好。
