发布内置FormData的NPM包时append方法报错如何解决

核心结论 #

不推荐面向浏览器端的NPM包内置FormData实现，你遇到的发布后formData.append传入File类型报错、本地运行正常的问题，本质是rollup构建环节错误引入了Node.js环境的FormData polyfill导致的类型不兼容，和你写的forEach遍历逻辑没有关系。

根因说明 #

浏览器原生提供的FormData接口可以直接识别标准File/Blob类型，但Node生态下的form-data包是为Node服务端环境设计的，它的append方法会对传入的参数做Node端的类型校验，无法识别浏览器原生的File对象，调用时就会抛出错误。
本地开发时你运行在Vite等构建工具的开发服务器下，代码直接在浏览器环境执行，调用的是原生FormData所以没有异常；rollup构建发布包时如果配置不当，会自动把Node端的form-data依赖打进产物里，就会触发这个报错。

修复步骤 #

• 修正rollup的模块解析配置，确保优先加载浏览器端依赖：

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'

export default {
  // 其余配置（input/output/vue插件等）保持不变
  plugins: [
    resolve({
      browser: true,
      preferBuiltins: false, // 关闭Node内置模块优先逻辑
      exportConditions: ['browser', 'module', 'import', 'default']
    }),
    commonjs(),
    // 其余插件保持不变
  ]
}

• 如果你项目里手动安装过form-data依赖，直接把它加入rollup的外部依赖列表，不要打进最终产物：

// rollup.config.js 对应配置项
export default {
  // 其余配置省略
  external: ['form-data']
}

• 如果你的包需要兼容IE等不支持原生FormData的旧浏览器，不要在顶层直接引入polyfill，加环境判断动态加载浏览器专用的polyfill即可：

if (typeof window !== 'undefined' && !window.FormData) {
  // 仅在原生FormData不存在时加载浏览器专用polyfill
  await import('formdata-polyfill')
}

验证方式 #

重新构建后，在生成的产物文件中搜索form-data相关的引入语句，确认没有把Node端的form-data实现打进包后，发布测试版本到NPM安装验证即可，append方法传入File类型的报错会直接消失。

内容的提问来源于stack exchange，提问作者Charles