企业官网建设流程全解析

• 开发工具
• 代码质量
• 静态分析

import/default是 eslint-plugin-import 中负责"静态分析"类别的一条核心规则：只要代码里写了import x from '...'这样的默认导入，它就要求被导入模块必须真的存在一个default导出，否则报错。本文以 docs/rules/default.md 为主体，结合规则源码、ExportMap 解析器、解析器实现与测试用例，完整讲解该规则的判定逻辑、底层工作原理、常见误报场景与 TypeScript 协作方式。

规则概述：它在哪些配置中生效

按文档头部标注，import/default在以下预设配置中以 error 级别启用：

• ❗errors（config/errors.js）：将import/default设为2，与no-unresolved、named、namespace、export并列，注释明确说明这是"运行时错误迟早会发生"的集合；
• ☑️recommended（config/recommended.js）：将import/default设为'error'，归属"analysis/correctness"（正确性分析）分组，与import/no-unresolved、import/named、import/namespace、import/export同级。

简单来说：默认导入（import foo from '...'）对应被导入模块的export default。如果被导入模块只导出了具名成员（export function bar() {}），或者根本没有导出，该规则就会在导入方报错——这正是它的核心职责：

If a default import is requested, this rule will report if there is no default export in the imported module.

规则源码：一次简洁的"查表"校验

规则完整实现位于 src/rules/default.js，整个逻辑非常精简，核心是checkDefault函数：

function checkDefault(specifierType, node) { const defaultSpecifier = node.specifiers.find( (specifier) => specifier.type === specifierType, ); if (!defaultSpecifier) { return; } const imports = ExportMapBuilder.get(node.source.value, context); if (imports == null) { return; } if (imports.errors.length) { imports.reportErrors(context, node); } else if (imports.get('default') === undefined) { context.report({ node: defaultSpecifier, message: `No default export found in imported module "${node.source.value}".`, }); } }

关键执行步骤可以拆解为四步：

1. 定位默认说明符：在 AST 节点里查找类型为ImportDefaultSpecifier（import foo from）或ExportDefaultSpecifier（ES7 的export foo from）的 specifier；找不到就直接返回，不产生任何报告；
2. 构建导出映射：调用ExportMapBuilder.get(node.source.value, context)解析被导入模块，得到该模块的导出信息表（ExportMap）。imports == null表示模块无法解析（未安装、扩展名无效、被 ignore 或不属于 ES 模块），此时同样静默返回；
3. 优先报告解析错误：如果目标模块在解析过程中出现语法错误，先通过imports.reportErrors(context, node)报告"Parse errors in imported module..."，而不是继续检查导出；
4. 检查 default 是否存在：调用imports.get('default')，如果返回undefined即不存在默认导出，则在默认说明符节点上报告No default export found in imported module "..."。

规则元信息里meta.type为'problem'、schema为空数组，说明它没有任何可配置选项，启用即用，开箱即得。

规则的访问器挂载：ImportDeclaration 与 ES7 export-from

create返回的访问器挂载了两个 AST 节点类型：

return { ImportDeclaration: checkDefault.bind(null, 'ImportDefaultSpecifier'), ExportNamedDeclaration: checkDefault.bind(null, 'ExportDefaultSpecifier'), };

• ImportDeclaration：覆盖普通的import foo from './foo'语句；
• ExportNamedDeclaration：覆盖 ES7 提案中的"export-from"语法，例如export bar from './bar'——这种写法相当于"从 './bar' 导入默认导出并以bar名义再导出"。此时规则同样会检查./bar是否存在默认导出，若没有则报错。测试中对应tests/src/rules/default.js里的用例（需要parsers.BABEL_OLD这类支持该语法的解析器）。

需要留意的是，常规的export { default as bar } from './bar'也是合法且会被检查的（测试中列为 valid），而 ES2022 的任意模块命名空间标识符语法export { "default" as bar } from "./bar"（要求ecmaVersion: 2022）同样得到支持。

判定示例：哪些写法合法、哪些报错

文档用一组非常直观的示例说明了判定边界。假设存在如下四个模块：

// ./foo.js export default function () { return 42 } // ./bar.js export function bar() { return null } // ./baz.js module.exports = function () { /* ... */ } // node_modules/some-module/index.js exports.sharedFunction = function shared() { /* ... */ }

以下写法被视为合法（valid）：

import foo from './foo' // assuming 'node_modules' are ignored (true by default) import someModule from 'some-module'

• ./foo.js有export default，天然通过；
• node_modules目录默认被import/ignore语义覆盖（详见下文"哪些模块会被跳过"），所以即使some-module只有exports.sharedFunction这种 CommonJS 风格导出，也不会被报告。

以下写法会被报告（invalid）：

import bar from './bar' // no default export found in ./bar import baz from './baz' // no default export found in ./baz

• ./bar.js只有具名导出export function bar()，没有export default，报错；
• ./baz.js使用的是module.exports = function () {...}，规则不会把它解释为 default 导出，因此同样报错。

底层原理：ExportMap 如何"读懂"被导入模块

规则本身只是"查表"，真正干活的是导出映射构建器 src/exportMap/builder.js。ExportMapBuilder.get(source, context)的完整调用链决定了"哪些模块会被纳入检查、哪些会被静默跳过"：

1. 解析路径：用resolve(source, context)把 import 源字符串解析成绝对路径，解析失败返回null；
2. 缓存检查：以context.cacheKey（由childContext依据 settings、parserOptions 与路径哈希生成，见 src/exportMap/childContext.js）作为键查询缓存，并对比文件mtime，未变化则直接复用，避免重复解析；
3. 扩展名校验：hasValidExtension不通过则跳过（比如.coffee、.css这类默认不在解析范围内的文件）；
4. ignore 校验：命中import/ignore配置的路径被缓存为null并跳过；
5. unambiguous 快速判别：先用正则快速试探，再对 AST 做二次确认（utils/unambiguous.js），确认文件确实属于"无歧义的 ES 模块"（即 AST 顶层存在ImportDeclaration/Export*Declaration这类节点）；
6. 解析与构建：调用parse解析源码，用ImportExportVisitorBuilder遍历 AST，把namespace、reexports、dependencies填入 ExportMap；
7. 动态导入兜底：若文件含import()动态导入（ImportExpression或Import调用），即使本身没有静态 import/export，也会被保留下来继续处理。

这里就能看出文档中那句"被忽略或无法无歧义判定为 ES 模块的路径不会被报告"的源码依据：步骤 4 与步骤 5 返回的null直接导致规则在imports == null时提前 return。

一个值得注意的实现细节：default 必须显式再导出

ExportMap 的get(name)实现 里有一段带注释的约定：// default exports must be explicitly re-exported (#328)。即export * from './x'这类星号再导出不会把x的 default 导出透传出去——default 必须通过export { default } from './x'显式再导出才算数。对应测试用例：

test({ code: 'import barDefault from "./re-export"', errors: ['No default export found in imported module "./re-export".'], }),

这正是文档没有细说、但从源码可以确认的重要边界：不要指望export *帮你搬运默认导出。

对 npm 包的支持：jsnext:main与 Redux 示例

文档特别提到：对于 npm 包，插件会优先从package.json的jsnext:main字段读取导出信息。Redux 的 npm 包就带了这个字段，因此可以被本规则正常检查。文档原文以 Redux 为例：import connectedApp from "./redux"在测试中属于 valid 用例（tests/src/rules/default.js 中的 #94 用例），因为 Redux 的jsnext:main指向的 ES 入口里存在默认导出。

jsnext:main的解析逻辑落实在解析器层：

• resolvers/node/index.js 的packageFilter：优先尝试pkg.module，失败后再尝试pkg['jsnext:main']，命中后把pkg.main改写为对应入口，使解析落到真正可静态分析的 ES 文件上；
• resolvers/webpack/index.js 则将'module'、'jsnext:main'纳入默认的packageMains查找顺序，测试见 resolvers/node/test/packageMains.js 与 resolvers/webpack/test/packageMains.js，它们分别验证了"jsnext 命中"、"module 优先于 jsnext"等场景。

另外，Node 核心模块（如import crypto from 'crypto'）在测试中被视为"永远有默认导出"（注释：core modules always have a default），这也是 valid 用例之一。

哪些模块会被静默跳过：ignore 与 unambiguous

文档给出两条跳过条件，这里补充它们在 README 与源码中的对应配置：

1. 被 import/ignore 忽略的模块：README 说明，import/ignore是一组正则字符串，凡是绝对路径命中其中任意一条的模块，"若没有找到 export 也不会报告"。默认情况下node_modules就在忽略之列，这解释了为什么import someModule from 'some-module'即使目标只有exports.sharedFunction也不会报错。示例配置：

{ "settings": { "import/ignore": [ "\\.coffee$", // fraught with parse errors "\\.(scss|less|css)$", // can't parse unprocessed CSS modules, either ], }, }

2. 无法无歧义判定为 ES 模块的文件：unambiguous的判定分两阶段——先用正则/(^|[;})])\s*(export|import)...|import\(/m快速过滤（负向命中说明文件"绝对不是模块"），再对 AST 检查是否存在Export*Declaration/Import*Declaration/TSExportAssignment节点确认。只有通过判定的文件才会进入导出收集流程；纯 CommonJS 文件（如module.exports = ...）在多数场景下会被这一步拦下。

测试中还验证了"路径大小写不敏感"的边界（非大小写敏感文件系统下，import bar from "./Named-Exports"指向named-exports会被正常报告，见 tests/src/rules/default.js 的default (path case-insensitivity)用例组）。

解析错误优先原则：先报 Parse errors，再谈缺导出

规则源码里有一行容易被忽略：if (imports.errors.length) { imports.reportErrors(context, node); }。也就是说，当被导入模块语法不合法时，规则报告的是"Parse errors in imported module '...'"而不是"缺默认导出"。

对应测试用例（tests/src/rules/default.js 的 invalid 区）使用了tests/files/jsx/FooES7.js这类含语法错误的文件（Babel 旧解析器下的Unexpected token = (6:16)）来验证：解析错误消息会优先于默认导出缺失消息出现。这条策略与named、namespace等静态分析规则一致，保证报错信息总能指向更根本的问题。

与 TypeScript 的协作：esModuleInterop 与 export assignment

虽然文档正文未展开，但从测试用例（tests/src/rules/default.js 的TypeScript上下文）可以看到该规则对 TS 生态的完整覆盖，测试覆盖了如下典型模式（均需配合eslint-import-resolver-typescript与import/parsers设置）：

• valid 用例：typescript-default、typescript-export-assign-default、typescript-export-assign-function、typescript-export-assign-default-reexport、typescript-export-assign-property，以及带tsconfig的typescript-export-assign-default-namespace、typescript-export-as-default-namespace等（注意：部分用例需要为 parserOptions 提供tsconfigRootDir，否则会因找不到 tsconfig 而走 invalid 分支）；
• invalid 用例：import foobar from "./typescript"、import React from "./typescript-export-assign-default-namespace"（缺少 tsconfigRootDir 时）等，均报告No default export found in imported module "..."。

背后的支撑逻辑在 src/exportMap/builder.js 的parse尾部：当esModuleInterop开启、模块确实有导出且尚未提供 default 时，会自动补一个 default 导出（exportMap.namespace.set('default', {})），这与 TypeScript 的esModuleInterop运行时语义保持一致，避免对合理 TS 写法产生误报。

何时不该使用这条规则：CommonJS 与运行时改导出的场景

文档的"When Not To Use It"部分给出两类明确场景：

1. 使用 CommonJS 或在运行时修改导出命名空间：规则基于静态分析，无法追踪运行时行为，因此很可能出现误报（false positives）；
2. module.exports = ...不会被当作 default 导出：当前规则不会把module.exports = function () {}解释成export default，这类写法会在导入方被报告。这正是前文./baz.js示例报错的原因，也是整个规则最广为人知的"限制"。

如果你的代码库以 CommonJS 为主、大量使用module.exports，或存在运行时篡改导出对象的模式，那么启用本规则前应先在少量目录试点，评估误报比例。

测试验证：规则的完整行为矩阵

规则行为在 tests/src/rules/default.js 中有系统化覆盖，除上文已引用的用例，valid 侧还包括：

• 无说明符导入import "./malformed.js"不报错；
• 空目录导入import foo from "./empty-folder"不报错；
• 具名导入import { foo } from "./default-export"不触发本规则（本规则只关心默认导入）；
• 默认 + 具名混用import bar, { baz } from "./default-export"；
• 默认导出类import CoolClass from "./default-class"、JSX 组件导入（jsx/MyCoolComponent.jsx）、ES7 export-from 系列（default-export-from.js、default-export-from-named.js）以及import/ignore: ['common']下的被忽略文件（default-export-from-ignored.js）。

invalid 侧则覆盖：纯具名导出模块、ES7export baz from的三种变体（含export baz, { bar } from、export baz, * as names from）、跳板再导出断裂（broken-trampoline）、星号导出不透传 default（re-export，#328）。

结语

import/default是 eslint-plugin-import 静态分析家族中行为最直接的一条规则：它在errors与recommended配置下默认开启、零配置参数，通过 ExportMap 的解析结果判断"默认导入是否有默认导出兜底"。理解它的关键在于三条边界——被 ignore / 非 ES 模块的路径跳过检查、module.exports不算 default、export *不透传 default。掌握这些边界后，你就能在纯 ESM 项目中放心启用它，把"默认导入指向空 default"这一类运行时错误提前到 lint 阶段拦截。

进一步可结合 named（具名导入对应具名导出）、namespace（命名空间解引用）与 no-named-as-default（禁止把具名导出误当默认导出）共同使用，构建完整的导入正确性防线。

• 开发工具
• 代码质量
• 静态分析