Parcel 2升级后React组件库出现require is not defined错误

问题概述 #

将Parcel从v1升级到v2后，构建给Ruby on Rails应用使用的React组件库时，JS/CSS文件能正常生成到指定路径，但浏览器加载时抛出Uncaught ReferenceError: require is not defined，生成的JS文件开头包含Node.js环境的require语句，而浏览器原生不支持该语法。

原因分析 #

1. 版本冲突：同时安装了Parcel v1的parcel-bundler和Parcel v2的parcel依赖，导致打包逻辑混乱。
2. 打包目标推断错误：Parcel v2默认根据package.json的main字段推断打包环境，若main指向输出目录的文件，会默认以Node.js环境打包，输出CommonJS格式代码（含require），无法在浏览器中运行。

解决方案 #

1. 移除Parcel v1依赖，消除版本冲突 #

执行命令卸载旧版本的Parcel依赖：

npm uninstall parcel-bundler

2. 明确指定打包目标为浏览器环境 #

有两种方式实现：

方式一：通过命令行参数指定

修改package.json中的scripts字段，添加--target browser参数：

"scripts": {
  "start": "parcel start app/index.jsx --host localhost --public-url /js --target browser",
  "build": "parcel build app/index.jsx --public-url /js --target browser"
}

方式二：通过package.json的targets字段配置

在package.json中新增targets字段，明确指定打包的上下文、输出格式和目录：

"targets": {
  "browser": {
    "source": "app/index.jsx",
    "distDir": "../public/js",
    "context": "browser",
    "outputFormat": "global"
  }
}

同时可简化scripts：

"scripts": {
  "start": "parcel start --host localhost --public-url /js",
  "build": "parcel build --public-url /js"
}

3. 修正package.json的main字段 #

原main字段指向输出目录的文件，会干扰Parcel的环境推断，建议修改为源码入口或直接删除：

"main": "app/index.jsx"

4. 清理缓存并重新构建 #

Parcel的缓存可能残留旧打包逻辑，清理后重新执行构建：

rm -rf .parcel-cache
npm run build

验证 #

重新构建后，检查生成的index.js文件开头，应该不再出现require语句，浏览器加载页面时也不会再抛出错误。

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