前端开发中为什么有些依赖必须import *引入使用详解

前言

在日常前端开发中，我们常常通过 import 来引入第三方库或模块。像这样：

import dayjs from "dayjs"
import { useState, useEffect } from 'react';

但你可能遇到过这样一种情况：有些依赖如果直接写成

import echarts from 'echarts';

会报错，或者运行时报 echarts is undefined，而必须写成：

import * as echarts from 'echarts';

这种现象可能会让你感到疑惑：为什么 ECharts 必须使用 import * 的方式？难道普通的默认导入不行吗？

本文将以 ECharts 为例，深入探讨这一问题的根源，并顺带梳理 ES Module（ESM）与 CommonJS（CJS）模块规范的差异，帮助你从底层理解 import * 背后的原因。

import的几种常见用法

在 ES Module 规范中，常见的几种导入方式包括：

默认导入

import xxx from 'module';

要求模块导出中必须有 export default xxx;。

具名导入

import { a, b } from 'module';

要求模块内部有 export const a、export const b 等具名导出。

命名空间导入

import * as mod from 'module';

将模块的所有导出整合到一个对象 模块 上。

通过ECharts 的导出方式深入import *

ECharts 的导出方式

熟悉完ES6的import的命名空间导入用法，我想echarts为什么需要通过import *答案已经很明确了。我们来看看echarts的入口文件：

这三句话分别代表了三种不同的模块兼容策略：

• import * as echarts from ...
  表示 ECharts 的所有导出都是 具名导出，并没有 export default。
• export as namespace echarts;
  这是为了兼容 UMD 模块，即在浏览器通过 <script> 直接引入时，可以挂载到全局变量 window.echarts 上。这样我们在代码里就能直接写：

echarts.init(document.getElementById('main'));

• export = echarts;
  这是 CommonJS 风格的导出，相当于 module.exports = echarts，用于兼容 Node.js 或老的打包工具。在这种情况下，TypeScript 需要你用 import * as echarts 来导入，而不是 import echarts from 'echarts'。

为什么 ECharts 没有用export default

看到这里，你可能还是有些困惑，如果导出入口改成

import * as echarts from './types/dist/echarts';
// Export for UMD module.
export as namespace echarts;
export default echarts;

我们代码里不是就可以使用下面的导入方式了吗？

import echarts from 'echarts';

原因主要有三点：

• 兼容性考虑

ECharts 是一个全球用户量非常大的可视化库，既要兼容 ESM，又要兼容 CommonJS，还要兼容 UMD（通过 <script> 引入时挂到 window.echarts 上）。
如果用 export default，对 CJS/UMD 的支持会比较麻烦，而 export = 在 TypeScript 下能天然兼容多种模块系统。

• 历史包袱

ECharts 最早是基于 UMD 格式发布的（早于 ES Module 普及）。
当时的入口写法更偏向：

if (typeof module === 'object' && module.exports) {
  module.exports = echarts;
} else {
  window.echarts = echarts;
}

后来迁移到 TypeScript 时，延续了 export = echarts 这种兼容写法，而不是强行改为 export default。

• API 设计思路

ECharts 官方的定位是“命名空间式 API”，也就是说，用户习惯通过 echarts.xxx() 方式调用。
为了保持这种语义一致性，团队没有提供 default export，而是把所有 API 都挂在一个 echarts 命名空间对象下。

import *的其他应用场景

除了 ECharts，还有一些库或工具函数常常需要使用 import *：

• 工具类库

有些工具库导出了非常多的函数，如果不想逐个引入，可以整合为一个命名空间对象。例如：lodash-es

import * as _ from 'lodash-es';

const arr = [1, 2, 2, 3, 4];
console.log(_.uniq(arr)); // [1, 2, 3, 4]

• 配置性常量集合

当一个模块只导出大量的常量或枚举值时，import * 可以避免逐个列出，写法更整洁。

例如：Node.js 内置 path 模块（ESM 版本）

import * as path from 'path';

console.log(path.sep);   // 当前系统路径分隔符（Windows: '', Linux/Mac: '/'）
console.log(path.resolve('./src'));

如何判断是否需要import *

如果你不确定一个库该怎么导入，可以采用以下几种方式：

看文档示例

查看源码或 d.ts 文件

如果不想找文档，可以直接打开项目的依赖

找到对应的包，导出方式在index.d.ts 文件中可以看到

Trae/Cursor智能提示

并不是所有第三方库都内置Ts支持，有index.d.ts文件，这个时候你可以借助AI编译器（如Trae或Cursor）的智能提示。

以Trae的注释生成代码为例：

总结 

到此这篇关于前端开发中为什么有些依赖必须 import *引入使用的文章就介绍到这了,更多相关import *引入依赖详解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！