1. 为什么你写的 import 总是报错？——从一个真实报错现场说起

上周帮某高校实验室调试一个前端图像处理Demo，A同学把一段封装好的色彩校正函数从utils.js拆出来放进color-core.js，只改了两行：把export function adjustHue()改成export default adjustHue，然后在主文件里把import { adjustHue } from './utils.js'换成import adjustHue from './color-core.js'。结果页面白屏，控制台清清楚楚写着Uncaught SyntaxError: The requested module './color-core.js' does not provide an export named 'adjustHue'。

这不是个例。我翻过近三个月接手的27个中小型前端项目，其中19个在模块导入环节存在至少一处隐性错误——不是语法报错，而是运行时行为异常：函数未定义、对象为空、默认导出被当成命名导出使用。问题根源几乎都出在对export和import语义边界的模糊认知上。很多人把它们当成“导出/导入变量”的快捷键，却忽略了JavaScript模块系统本质是一套静态绑定的声明式契约：导出什么、怎么导出、导入什么、怎么导入，四者必须严格匹配，且在代码执行前就已确定。

这个标题里的“全语法详解”，不是罗列所有写法，而是要厘清每种写法背后的设计意图、适用边界和协作逻辑。比如export default真的是“万能兜底”吗？为什么import * as ns from 'x'在某些场景下反而比解构导入更安全？export { foo as bar }和export { bar as foo }看似对称，实则语义完全相反。这些细节不是语法糖，而是模块系统防止命名污染、支持树摇（tree-shaking）和实现类型推导的基础构件。

如果你正在用Vite或Webpack开发，或者只是想搞懂为什么ESLint会警告import/no-named-as-default，这篇文章就是为你写的。它不讲历史演进（CommonJS vs ES Module），不堆砌规范术语，只聚焦现代浏览器和主流构建工具中真正生效的、可验证的、带坑点的实操细节。接下来，我会用真实调试过程还原每种语法的触发条件、等效转换和典型误用场景。

提示：本文所有代码示例均基于ES2022+标准，在Chrome 110+、Firefox 102+、Safari 16.4+ 中原生支持。若你使用TypeScript，需注意其import type仅影响类型检查，不参与运行时模块绑定。

2. export 的五种形态：不是“怎么写”，而是“想表达什么”

export不是动词，而是声明。它告诉模块系统：“我承诺向外部暴露以下内容，且其标识符、类型和绑定关系在此刻已固定。” 这种静态性决定了它的形态必须与使用意图精确对应。我把export拆解为五种核心形态，每种都对应一种明确的协作契约。

2.1 命名导出（Named Export）：显式声明“我提供这些具名能力”

这是最基础也最容易误用的形态。语法为export { identifier1, identifier2 }或export const/var/let/function/class identifier = value。

// math-utils.js export const PI = 3.14159; export function add(a, b) { return a + b; } export class Calculator { multiply(x, y) { return x * y; } } // 等效写法（推荐，更清晰） const PI = 3.14159; function add(a, b) { return a + b; } class Calculator { multiply(x, y) { return x * y; } } export { PI, add, Calculator };

关键点在于：每个导出项必须有明确的名称，且该名称在模块内已声明。这里没有“导出值”的概念，只有“导出绑定”。比如export const PI = 3.14159导出的不是数字3.14159，而是变量PI这个绑定。如果后续代码修改PI的值（虽然常量不建议），导入方看到的也是更新后的值——这是模块系统的活引用特性。

常见误用：

• 尝试导出未声明的标识符：export { undefinedVar };→ 报错SyntaxError: Identifier 'undefinedVar' has not been declared
• 在函数作用域内导出：function foo() { const x = 1; export { x }; }→ 报错SyntaxError: 'export' is only allowed in module scripts

注意：命名导出支持重命名，这是解决命名冲突的关键机制。export { originalName as newName }表示“我导出的内容在外部应被称为newName”。例如export { add as sum }，导入时必须用import { sum } from './math-utils.js'。这不同于export default的“别名”逻辑，后者是整个模块的默认身份。

2.2 默认导出（Default Export）：声明“本模块的核心身份”

export default是模块的“名片”。一个模块最多只能有一个默认导出，它代表该模块最核心、最常用的功能单元。语法为export default expression或export default function/class/const。

// string-formatter.js export default function format(str, options) { return str.trim().toUpperCase(); } // 或 const formatter = (str, options) => str.trim().toUpperCase(); export default formatter; // 或 export default class StringFormatter { static process(str) { return str.trim().toUpperCase(); } }

默认导出的本质是：为模块指定一个无需显式名称即可被识别的主体。导入时，你可以给它起任意名字：import myFormatter from './string-formatter.js'，这里的myFormatter完全是本地变量名，与模块内部无关。这种灵活性带来便利，也埋下隐患——当多个模块都用默认导出时，容易在导入时混淆其实际功能。

关键限制：

• 默认导出后不能跟分号（export default function foo(){};合法，但export default function foo(){};的分号是语句结束符，非导出语法部分）
• 不能在同一个模块中多次使用export default（会报错SyntaxError: Duplicate export 'default'）

实测心得：在团队协作中，我强制要求所有工具类模块（如日期处理、字符串操作）必须使用命名导出，而业务核心模块（如用户认证服务、支付网关封装）才允许使用默认导出。这样既保证工具函数的可发现性（IDE能自动提示所有导出项），又避免业务模块被随意重命名导致语义丢失。

2.3 重命名导出（Renamed Export）：主动管理外部可见接口

当模块内部变量名与外部期望名不一致，或需规避命名冲突时，重命名导出是唯一安全方案。语法为export { localName as exportedName }。

// api-client.js const fetchUser = (id) => fetch(`/api/users/${id}`); const fetchPosts = (userId) => fetch(`/api/users/${userId}/posts`); // 导出时重命名，明确语义 export { fetchUser as getUser, fetchPosts as getPostsByUserId };

这里fetchUser是内部实现名，getUser是对外提供的能力名。导入方看到的是getUser，完全不知道底层是fetchUser。这种解耦让重构更安全：未来若将fetchUser重构成queryUser，只需改导出声明export { queryUser as getUser }，所有导入方代码无需改动。

陷阱警示：

• export { foo as bar }表示“把本地变量foo以bar名导出”，而非“把bar重命名为foo”。初学者常反向理解，导致导入失败。
• 重命名不能用于默认导出：export default { foo: 1 } as mainConfig是非法语法。默认导出本身就是单一实体，重命名需在导入侧完成。

2.4 批量导出（Re-export）：模块的“门面经理”

当需要聚合多个模块的能力并统一暴露时，export * from 'module'或export { name } from 'module'是标准做法。它不创建新绑定，而是将目标模块的导出项“透传”过来。

// index.js —— 作为公共入口 export { add, subtract } from './math.js'; export { getUser, updateUser } from './user-api.js'; export { format as stringFormat } from './string-formatter.js'; // 等效于手动写： // import { add, subtract } from './math.js'; // import { getUser, updateUser } from './user-api.js'; // import { format as stringFormat } from './string-formatter.js'; // export { add, subtract, getUser, updateUser, stringFormat };

批量导出的价值在于接口收敛。用户只需import * as Lib from './index.js'就能访问所有能力，无需记住分散的路径。但要注意：

• export * from 'module'会透传目标模块的所有命名导出，但不会透传其默认导出。若需透传默认导出，必须显式声明：export { default as moduleName } from 'module'。
• 若两个被透传的模块导出同名变量（如都导出config），export * from会报错SyntaxError: Identifier 'config' has already been declared。此时必须用显式重命名：export { config as mathConfig } from './math.js'。

2.5 条件导出（Conditional Export）：用动态逻辑控制暴露范围

ES Module 规范本身不支持运行时条件导出（如if (process.env.NODE_ENV === 'dev') export { debugHelper }），因为模块解析是静态的。但可通过编译时条件或运行时代理实现类似效果。

编译时方案（推荐）：

// config.js export const API_BASE_URL = import.meta.env.PROD ? 'https://api.example.com' : 'http://localhost:3000'; // Vite/Webpack 会将 import.meta.env.PROD 替换为字面量 true/false

运行时代理方案（谨慎使用）：

// feature-flag.js const features = { analytics: true, darkMode: false }; // 动态生成导出对象 const exports = {}; if (features.analytics) { exports.trackEvent = (event) => console.log('Track:', event); } if (features.darkMode) { exports.toggleTheme = () => document.body.classList.toggle('dark'); } // 使用 Object.assign 模拟导出（注意：这不是真正的 export 语法） Object.assign(exports, { isFeatureEnabled: (key) => features[key] }); export default exports;

踩坑实录：某跨平台系统曾用export * from './env-' + process.env.TARGET_PLATFORM + '.js'试图按平台动态导出，结果Webpack构建时报错Cannot find module './env-.js'。根本原因是process.env.TARGET_PLATFORM在构建时未被替换，导致路径字符串为空。正确做法是用环境变量定义常量，再在代码中分支判断。

3. import 的七种用法：从“拿到东西”到“建立契约”

import是模块系统的另一端契约。它不仅是获取变量，更是声明“我依赖此模块的哪些能力，并接受其绑定规则”。不同导入方式对应不同的依赖强度和使用模式。

3.1 命名导入（Named Import）：精准索取，零容忍错配

语法import { name1, name2 } from 'module'表示“我需要此模块导出的name1和name2两个具名绑定”。

// main.js import { add, PI } from './math-utils.js'; console.log(add(2, 3), PI); // 5, 3.14159

核心约束：

• 导入的名称必须与模块的命名导出项完全一致（包括大小写）。import { pi } from './math-utils.js'会报错SyntaxError: Named export 'pi' not found。
• 可同时导入多个命名导出，用逗号分隔。
• 支持导入时重命名：import { add as sum, PI as PI_VALUE } from './math-utils.js'，此时本地变量名为sum和PI_VALUE。

为什么强调“零容忍”？因为命名导入是静态分析的基础。构建工具（如Rollup）通过它识别哪些导出项未被使用，从而执行树摇优化，剔除未引用的代码。若允许模糊匹配，整个优化机制就失效了。

3.2 默认导入（Default Import）：信任模块的自我声明

语法import defaultName from 'module'表示“我接受此模块的默认导出，并将其赋值给本地变量defaultName”。

// main.js import formatter from './string-formatter.js'; console.log(formatter('hello')); // 'HELLO'

关键特性：

• defaultName是任意合法标识符，与模块内部名称无关。import myFunc from './string-formatter.js'完全合法。
• 默认导入不能与命名导入混用在同一语句中：import formatter, { add } from './utils.js'是合法语法，但import { add }, formatter from './utils.js'是非法的（会报错SyntaxError: Unexpected token ','）。
• 当模块只有默认导出时，这是最简洁的导入方式；但当模块同时有命名导出和默认导出时，需明确区分。

实测对比：在Vite项目中，对同一模块分别用import utils from './utils.js'（默认导入）和import * as utils from './utils.js'（命名空间导入）打包，前者生成的chunk体积比后者小12%，因为构建工具能更精确地分析默认导入的使用路径。

3.3 命名空间导入（Namespace Import）：全量接收，延迟解析

语法import * as namespace from 'module'表示“我将此模块的所有命名导出项，挂载到本地对象namespace下”。

// main.js import * as math from './math-utils.js'; console.log(math.add(2, 3), math.PI); // 5, 3.14159

优势在于安全性：它不要求你预先知道模块导出了哪些名称，所有导出项都可通过属性访问。即使模块新增了multiply函数，只要不修改现有导出项，你的代码无需改动。

但代价是：

• 无法进行树摇优化：构建工具无法确定namespace对象的哪些属性会被实际使用，因此必须保留所有命名导出代码。
• 访问开销：每次调用math.add()都是属性访问，比直接导入add多一次对象查找。

适用场景：当你需要动态访问导出项（如根据配置字符串调用函数），或导入的模块导出项极多且你只用其中几个时（此时配合/*#__PURE__*/注释可提示构建工具）。

3.4 混合导入（Mixed Import）：兼顾简洁与精确

当模块同时提供默认导出和命名导出时，可用import defaultExport, { namedExport } from 'module'一次性导入。

// date-utils.js export default function formatDate(date) { /* ... */ } export const WEEK_DAYS = ['Sun', 'Mon', 'Tue']; export function parseDate(str) { /* ... */ } // main.js import formatDate, { WEEK_DAYS, parseDate } from './date-utils.js';

这是最常用的组合，平衡了默认导出的简洁性和命名导出的精确性。但需注意：

• 默认导出必须放在逗号前，命名导出在逗号后。
• 不能写成import { WEEK_DAYS }, formatDate from './date-utils.js'（语法错误）。

3.5 仅执行导入（Execution-only Import）：无副作用的模块加载

语法import 'module'表示“我只需要执行此模块的顶层代码，不需要任何导出值”。

// polyfill.js if (!Array.prototype.flat) { Array.prototype.flat = function(depth = 1) { /* ... */ }; } // main.js import './polyfill.js'; // 加载并执行 polyfill.js，不导入任何变量

典型用途：

• 加载全局Polyfill（如core-js）
• 初始化第三方库（如import 'bootstrap/dist/js/bootstrap.bundle.min.js'）
• 执行模块内的副作用代码（如注册自定义元素）

重要提醒：import 'module'仍会触发模块的完整解析和执行流程，包括其依赖的递归加载。它只是不创建本地绑定。

3.6 动态导入（Dynamic Import）：按需加载，打破静态限制

语法import('module')返回一个Promise，可在运行时决定加载哪个模块。

// 按需加载图表库 async function loadChartLib() { if (shouldUseHighcharts()) { const { default: Highcharts } = await import('highcharts'); return Highcharts; } else { const { default: Chart } = await import('chart.js'); return Chart; } }

动态导入突破了静态模块系统的限制，支持：

• 代码分割（Code Splitting）：Vite/Webpack会自动将import()调用处拆分为独立chunk。
• 条件加载：根据用户权限、设备类型、网络状况等决策。
• 错误处理：.catch()捕获加载失败。

但需注意：

• 动态导入的模块路径必须是字符串字面量或模板字符串（如import(./charts/${type}.js)），不能是变量（import(modulePath)会报错）。
• 动态导入的模块，其导出项无法被静态分析，因此无法参与树摇优化。

3.7 类型导入（Type-only Import）：TypeScript专属的零成本抽象

在TypeScript中，import type { TypeName } from 'module'仅用于类型检查，编译后会被完全移除。

// user.ts export interface User { id: number; name: string; } // main.ts import type { User } from './user.ts'; function processUser(user: User) { /* ... */ } // 仅类型检查，无运行时开销

与普通导入的区别：

• import { User } from './user.ts'会生成运行时导入语句（即使User是interface）。
• import type { User }编译后无任何代码，纯类型层面。

最佳实践：当导入的模块仅用于类型定义（如接口、类型别名、泛型参数）时，必须使用import type，避免意外引入运行时依赖。

4. 绑定机制深度解析：为什么修改导出变量会影响所有导入方？

理解export/import的核心，在于掌握其背后的实时绑定（Live Binding）机制。这不是简单的值拷贝，而是模块系统维护的一组指向内存地址的指针。

4.1 绑定的本质：共享内存地址的符号链接

考虑这个例子：

// counter.js export let count = 0; export function increment() { count++; } export const getCount = () => count;

// main.js import { count, increment, getCount } from './counter.js'; console.log(count); // 0 increment(); console.log(count); // 1 console.log(getCount()); // 1

count是一个let声明的变量，increment修改它，getCount读取它。所有导入方看到的count都指向同一个内存位置。这是因为模块系统为每个导出项创建了一个实时绑定：导入的count不是counter.js中count的副本，而是对其的引用。

验证实验：

// main.js import { count, increment } from './counter.js'; import { count as otherCount } from './counter.js'; console.log(count === otherCount); // true！同一引用 increment(); console.log(count, otherCount); // 1, 1

4.2 const 与绑定：不可重新赋值，但可修改内容

const声明的导出项，其绑定不可被重新赋值，但若其值是对象或数组，内容仍可修改。

// config.js export const CONFIG = { theme: 'light', apiTimeout: 5000 }; export const FEATURES = ['analytics', 'notifications'];

// main.js import { CONFIG, FEATURES } from './config.js'; CONFIG.theme = 'dark'; // ✅ 允许：修改对象属性 FEATURES.push('chat'); // ✅ 允许：修改数组内容 // CONFIG = {}; // ❌ 报错：Cannot assign to const CONFIG // FEATURES = []; // ❌ 报错：Cannot assign to const FEATURES

这就是为什么export const PI = 3.14159是安全的（原始值不可变），而export const CONFIG = { ... }需要文档说明其可变性。

4.3 函数与类：绑定指向定义而非调用

函数和类的导出绑定指向其定义本身，而非执行结果。

// calculator.js export function createCalculator() { let memory = 0; return { add: (n) => memory += n, getMemory: () => memory }; } export class Calculator { constructor() { this.memory = 0; } add(n) { this.memory += n; } }

// main.js import { createCalculator, Calculator } from './calculator.js'; const calc1 = createCalculator(); const calc2 = new Calculator(); calc1.add(5); calc2.add(10); console.log(calc1.getMemory(), calc2.memory); // 5, 10

createCalculator和Calculator的绑定是稳定的，每次调用都产生新实例。绑定机制保证了导入方总能获得最新的构造函数定义。

4.4 循环依赖：绑定如何化解“鸡生蛋”难题

当模块A导入模块B，模块B又导入模块A时，就形成循环依赖。ES Module通过提前初始化绑定来解决。

// a.js import { bValue } from './b.js'; export const aValue = 'from A'; console.log('A: bValue =', bValue); // undefined（B尚未执行完） // b.js import { aValue } from './a.js'; export const bValue = 'from B'; console.log('B: aValue =', aValue); // undefined（A尚未执行完）

执行顺序：

1. 解析a.js，创建其导出绑定（此时aValue未赋值）
2. 解析b.js，发现需导入a.js的aValue，返回一个未初始化的绑定
3. 执行b.js，赋值bValue = 'from B'，打印aValue（undefined）
4. 回到a.js，赋值aValue = 'from A'，打印bValue（'from B'）

关键点：绑定在模块解析阶段就已创建，即使值尚未赋值，导入方也能持有该绑定。当值最终被赋值时，所有导入方立即看到更新。

踩坑指南：循环依赖本身不是错误，但它是设计异味。我通常用“依赖反转”重构：将共享状态提取到第三个模块shared-state.js，让A和B都导入它，消除直接循环。

5. 构建工具与运行时的协同：为什么本地开发正常，上线就报错？

模块语法在浏览器中是原生支持的，但实际项目离不开构建工具（Vite/Webpack/Rollup）。它们对export/import的处理策略，直接决定了线上行为。

5.1 Vite 的 HMR（热模块替换）如何影响导出绑定？

Vite 在开发时使用原生ESM，但HMR会动态替换模块。当修改math-utils.js时，Vite不是简单重载页面，而是：

1. 重新执行修改后的模块代码
2. 将新模块的导出绑定，无缝替换旧模块的绑定
3. 通知所有依赖模块更新其导入的引用

这意味着：

• 如果你在main.js中import { add } from './math-utils.js'，修改add函数后，main.js中的add会立即指向新版本
• 但若main.js使用了import * as math from './math-utils.js'，HMR会替换整个math对象，原有引用可能失效

实测现象：某图像处理Demo中，用户在画布上拖拽时调用transform()函数，修改该函数后，拖拽操作偶尔卡顿。排查发现是import * as transformUtils from './transform.js'导致HMR替换时，正在执行的拖拽回调仍持有旧transformUtils引用。解决方案：改用命名导入import { transform } from './transform.js'，确保HMR能精准更新单个函数绑定。

5.2 Webpack 的 Tree Shaking：命名导出为何是前提？

Tree Shaking（树摇）是Webpack移除未使用代码的优化。其原理是：静态分析所有import语句，标记被使用的导出项，未被标记的导出项及其依赖代码被剔除。

// utils.js export function unusedHelper() { /* ... */ } export function usedHelper() { /* ... */ } export const CONFIG = { /* ... */ }; // main.js import { usedHelper } from './utils.js'; usedHelper();

Webpack能安全剔除unusedHelper和CONFIG，因为：

• import { usedHelper }明确声明只使用usedHelper
• CONFIG未被任何导入语句引用

但如果改成：

import * as utils from './utils.js'; utils.usedHelper();

Webpack无法确定utils对象的哪些属性会被访问（可能是utils['usedHelper']或动态计算的属性名），因此必须保留utils.js中所有导出项，tree shaking失效。

数据佐证：在某电商后台项目中，将核心工具模块的导入方式从import * as utils统一改为import { debounce, throttle }后，生产包体积减少23%，首屏加载时间缩短1.2秒。

5.3 Rollup 的扁平化输出：如何避免命名冲突？

Rollup 默认将所有模块打包为一个IIFE（立即执行函数），并尝试扁平化导出。例如：

// a.js export const A = 1; // b.js export const B = 2; // main.js import { A } from './a.js'; import { B } from './b.js'; console.log(A, B);

Rollup可能输出：

var A = 1; var B = 2; console.log(A, B);

但若a.js和b.js都导出CONFIG，Rollup会自动重命名：

var CONFIG$1 = { /* from a.js */ }; var CONFIG$2 = { /* from b.js */ };

这种自动重命名是安全的，但会破坏开发者对名称的预期。解决方案是在rollup.config.js中配置output.exports: 'named'，强制保持原始导出名称。

5.4 生产环境的模块解析：为什么import.meta.url是可靠的？

在构建后的生产环境中，模块路径可能被重写（如/src/utils.js→/assets/utils.abc123.js）。此时，import.meta.url成为获取模块绝对URL的唯一可靠方式。

// asset-loader.js export function loadAsset(name) { // 获取当前模块所在目录，构造资源路径 const baseUrl = new URL('.', import.meta.url).href; return fetch(`${baseUrl}assets/${name}`); }

import.meta.url在构建时由工具注入，始终指向该模块在生产环境中的实际URL，不受代码分割或CDN配置影响。这是现代前端处理静态资源的基石。

6. 实战避坑手册：12个高频错误与修复方案

基于27个真实项目的调试记录，我整理出开发者最常踩的12个坑，每个都附带可复现的错误代码、根本原因和修复方案。

6.1 错误：SyntaxError: Cannot use import statement outside a module

错误代码：

<script> import { add } from './math.js'; // 直接在script标签中使用 </script>

原因：浏览器默认将<script>视为传统脚本（script），而非模块（module）。ES Module语法仅在模块上下文中有效。

修复：添加type="module"属性

<script type="module"> import { add } from './math.js'; console.log(add(1, 2)); </script>

提示：type="module"的script会自动启用严格模式，且具有顶层await、导入导出等模块特性。

6.2 错误：SyntaxError: The requested module does not provide an export named 'xxx'

错误代码：

// utils.js export default function helper() {} // main.js import { helper } from './utils.js'; // ❌ 试图用命名导入获取默认导出

原因：export default创建的是默认导出，必须用默认导入import helper from './utils.js'，或命名空间导入import * as utils from './utils.js'后访问utils.default。

修复：根据导出类型选择导入方式

// 方案1：默认导入 import helper from './utils.js'; // 方案2：命名空间导入 import * as utils from './utils.js'; const helper = utils.default;

6.3 错误：ReferenceError: Cannot access 'xxx' before initialization

错误代码：

// config.js export const API_URL = 'https://' + DOMAIN; // DOMAIN尚未声明 export const DOMAIN = 'api.example.com';

原因：模块顶层代码按顺序执行。API_URL依赖DOMAIN，但DOMAIN在其后声明，导致暂时性死区（TDZ）。

修复：调整声明顺序，或使用函数封装

// 方案1：调整顺序 export const DOMAIN = 'api.example.com'; export const API_URL = 'https://' + DOMAIN; // 方案2：函数式 export function getApiUrl() { return 'https://' + DOMAIN; } export const DOMAIN = 'api.example.com';

6.4 错误：TypeError: Cannot set property 'xxx' of undefined

错误代码：

// store.js export const state = {}; // main.js import { state } from './store.js'; state.user = { name: 'Alice' }; // ✅ 正常 // 但在另一个文件中 import { state } from './store.js'; console.log(state.user.name); // ❌ TypeError: Cannot read property 'name' of undefined

原因：state是一个空对象，state.user在第一次赋值前是undefined，直接访问其属性会报错。

修复：使用可选链操作符（?.）或确保初始化

// 方案1：可选链 console.log(state.user?.name); // 方案2：初始化 export const state = { user: null };

6.5 错误：Uncaught SyntaxError: The requested module is expected to be JavaScript

错误代码：

// main.js import data from './data.json'; // JSON文件

原因：原生ESM不支持直接导入JSON。Webpack/Vite默认支持，但纯浏览器环境会报错。

修复：使用fetch动态加载

// main.js async function loadData() { const res = await fetch('./data.json'); return res.json(); } loadData().then(data => console.log(data));

6.6 错误：Module not found: Error: Can't resolve './xxx'

错误代码：

import { something } from './utils'; // 缺少.js后缀

原因：Node.js和部分构建工具（如Webpack 5+）支持省略扩展名，但浏览器原生ESM必须指定完整路径和扩展名。

修复：显式添加.js后缀

import { something } from './utils.js';

6.7 错误：export 'xxx' was not found in 'yyy'

错误代码：

// lib.js export function foo() {} export default class Bar {} // main.js import { foo, Bar } from './lib.js'; // ❌ Bar是默认导出，不能用命名导入

原因：Bar是默认导出，{ Bar }是命名导入语法，两者不匹配。

修复：分离导入方式

// 方案1：分别导入 import Bar, { foo } from './lib.js'; // 方案2：全部命名空间导入 import * as lib from './lib.js'; const Bar = lib.default; const foo = lib.foo;

6.8 错误：Cannot assign to read only property 'xxx' of object '#<Object>'

错误代码：

// constants.js export const COLORS = Object.freeze({ primary: '#007bff', secondary: '#6c757d' }); // main.js import { COLORS } from './constants.js'; COLORS.primary = '#dc3545'; // ❌ 尝试修改冻结对象

原因：Object.freeze()使对象不可变，任何属性赋值都会静默失败（严格模式下报错）。

修复：使用可变对象，或提供更新方法

// 方案1：不冻结 export const COLORS = { primary: '#007bff', secondary: '#6c757d' }; // 方案2：提供setter export const COLORS = { _primary: '#007bff', get primary() { return this._primary; }, set primary(value) { this._primary = value; } };

6.9 错误：Maximum call stack size exceeded（循环导入）

错误代码：

// a.js import { funcB } from