前端模块化指南：CJS 与 ESM 的区别与混用

1. 核心概念CJS (CommonJS)Node.js 的原生模块系统。语法require()导入module.exports导出。特点同步加载主要用于服务端。ESM (ECMAScript Modules)JavaScript 的官方标准模块系统。语法import导入export导出。特点静态分析异步加载现代浏览器和前端开发的标准。2. 如何判断项目类型查看项目根目录下的package.json文件type: module项目为ESM模式。.js文件被视为 ESM必须使用import/export。如需使用 CJS文件后缀必须改为.cjs。未设置type或type: commonjs项目为CJS模式默认。.js文件被视为 CJS必须使用require/module.exports。如需使用 ESM文件后缀必须改为.mjs。3. 为什么 Vue 2 项目是 CJS却能用 import这是最容易混淆的地方。项目分为两个“世界”A. Node.js 构建环境运行者Node.js 进程。受影响文件根目录配置文件如vue.config.js、构建脚本如build/index.js。规则受package.json的type控制。如果是默认 CJS 项目这些文件必须使用require。B. 浏览器运行环境运行者用户的浏览器。中间人Webpack / Vite构建工具。受影响文件src/目录下的所有源码.vue,.js等。规则不受 Node.jstype控制。构建工具会读取src下的代码将import翻译成浏览器可执行的代码。因此在src下请尽情使用import。4. 实战判断法则哪些文件能用 import不需要死记硬背遵循以下逻辑法则一看位置src/目录下✅能用import。这是前端源码由 Webpack/Vite 处理默认支持 ESM。根目录配置文件如vue.config.js❌不能用import。这是 Node.js 脚本受package.json控制。默认 CJS 下必须用require。法则二看后缀.mjs强制视为 ESM必须用import。.cjs强制视为 CJS必须用require。.js看package.json的type设置默认是 CJS。法则三看报错兜底如果报错SyntaxError: Cannot use import statement outside a ES module说明该文件由 Node.js 直接运行且处于 CJS 模式。解决将import改回require或者将文件后缀改为.mjs并在package.json开启 ESM。5. 图片导入总结类型位置引用方式说明本地图片src/assetsimport img from ...推荐。Webpack 会处理路径和优化。静态资源public//filename.ext绝对路径原封不动复制到 dist。网络图片服务器http://...直接绑定字符串 URL。一句话总结在 Vue 2 / Webpack 项目中src里写import根目录配置写require。如果不确定试着用import报错了就改回来。