企业官网建设流程全解析

create-react-app 组件导入完全指南：ES6 模块规范与 jsconfig 绝对路径配置实战

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app

在 React 项目里组织代码时，"如何正确 import 一个组件"看似简单，实则暗藏 default 与 named 导出混用的经典坑。本文基于 create-react-app 官方文档 importing-a-component.md 展开，完整讲解项目对 ES6 模块（import/export）的支持方式、default/named 导出的取舍规则，以及如何通过jsconfig.json/tsconfig.json配置baseUrl启用绝对路径导入，并结合react-scripts源码深入剖析这套能力在 webpack 与 Jest 两侧的落地机制。读完本文，你既能写出规范可运行的组件导入代码，也能看懂 CRA 是如何把你的导入语句编译进构建链路的。

一、ES6 模块：CRA 的默认导入方式

CRA 项目底层由 webpack 驱动，因此完整支持 ES6 模块语法。虽然require()和module.exports这类 CommonJS 写法依然可用，但官方文档明确鼓励开发者改用import和export。

一个典型的组件定义（Button.js）如下，注意文件末尾的export default是关键——组件文件必须显式默认导出：

import React, { Component } from 'react'; class Button extends Component { render() { // ... } } export default Button; // Don't forget to use export default!

另一个组件（DangerButton.js）则通过相对路径引入上一步定义的组件：

import React, { Component } from 'react'; import Button from './Button'; // Import a component from another file class DangerButton extends Component { render() { return <Button color="red" />; } } export default DangerButton;

这两个示例完整覆盖了组件导入的两步闭环：定义侧export default导出、消费侧import X from默认导入。

二、default 导出与 named 导出的取舍规则

文档特别警告：default 导出与 named 导出的区别是常见错误来源。官方建议的取舍原则是：

• 当模块只导出单一内容时（例如一个组件），坚持使用 default 导入和导出，即export default Button配import Button from './Button'。组件文件几乎都属于这种情况；
• named 导出适合导出多个函数的工具模块（utility modules），按需导入其中某个函数；
• 一个模块最多只能有一个 default 导出，但可以有任意多个 named 导出。

记住这条规则即可规避绝大多数"导入得到 undefined"的运行时问题：看导出方式，再决定导入时是否需要花括号。

三、绝对路径导入：jsconfig.json 与 tsconfig.json

3.1 配置方式

CRA 支持将应用配置为允许使用绝对路径导入模块，方式是在项目根目录放置jsconfig.json（JavaScript 项目）或tsconfig.json（TypeScript 项目）。如果你在项目中使用了 TypeScript，那么tsconfig.json通常已经存在，直接在它的compilerOptions中配置baseUrl即可。

JavaScript 项目的示例jsconfig.json（如文件不存在可自行创建）：

{ "compilerOptions": { "baseUrl": "src" }, "include": ["src"] }

TypeScript 项目则把baseUrl设置写入项目tsconfig.json的compilerOptions中，写法与上面一致。

3.2 使用绝对路径导入

配置完成后，若Button.js位于src/components/Button.js，就可以这样导入，而无需层层写相对路径：

import Button from 'components/Button';

注意导入路径是相对于baseUrl（即src）的：components/Button实际指向src/components/Button.js。

3.3 测试项目中的真实验证

仓库中自带了一个最小验证工程 test/fixtures/jsconfig，其配置正是文档中推荐的形态 test/fixtures/jsconfig/jsconfig.json：

{ "compilerOptions": { "baseUrl": "src" } }

它的 src/App.js 用绝对路径导入了同目录下的工具函数：

import load from 'absoluteLoad'; // 等价于 import load from './absoluteLoad'

对应测试 src/App.test.js 名为'loads modules absolutely with baseUrl'，通过 ReactDOM 渲染验证绝对导入在运行时无缝工作；而 index.test.js 进一步保证该工程在 development 启动、production 构建、Jest 测试三条链路上全部通过——绝对路径导入不仅 webpack 构建可用，测试环境同样可用。

四、源码级剖析：CRA 如何实现绝对导入

以下结论均来自react-scripts源码，帮助理解配置项背后的真实行为。

4.1 统一入口：config/modules.js

核心逻辑集中在 packages/react-scripts/config/modules.js。它在项目启动时检查根目录是否存在tsconfig.json/jsconfig.json（路径定义见 packages/react-scripts/config/paths.js 中的appTsConfig与appJsConfig），并读取其中的compilerOptions.baseUrl，产出三份结果供构建链各环节消费：

• additionalModulePaths：追加到模块搜索路径；
• webpackAliases：webpack 的resolve.alias；
• jestAliases：Jest 的moduleNameMapper。

getAdditionalModulePaths的分支逻辑值得细看：

// baseUrl 为 node_modules（默认行为）→ 什么都不做 if (path.relative(paths.appNodeModules, baseUrlResolved) === '') { return null; } // 允许 baseUrl 指向 src → 将 src 加入模块搜索路径 if (path.relative(paths.appSrc, baseUrlResolved) === '') { return [paths.appSrc]; } // baseUrl 为项目根目录 → 不加入模块路径 // （src 之外的源文件不会经过 babel 转译，不能直接按模块导入） if (path.relative(paths.appPath, baseUrlResolved) === '') { return null; } // 其他值直接报错 throw new Error( chalk.red.bold( "Your project's `baseUrl` can only be set to `src` or `node_modules`." + ' Create React App does not support other values at this time.' ) );

由此可以得到两个重要限制：baseUrl只允许设置为src或node_modules，其他取值会直接抛错；两者都未设置时不产生任何效果。同时该文件还校验：若tsconfig.json与jsconfig.json同时存在，会直接报错要求删除jsconfig.json（modules.js#L107-L111）。

4.2 webpack 侧：resolve.modules 与 alias

packages/react-scripts/config/webpack.config.js 中，上述结果被注入 webpack 的resolve配置：

resolve: { modules: ['node_modules', paths.appNodeModules].concat( modules.additionalModulePaths || [] ), // ... alias: { 'react-native': 'react-native-web', // ... ...(modules.webpackAliases || {}), }, },

也就是说，baseUrl: "src"时src目录被追加进 webpack 的模块搜索目录，import Button from 'components/Button'因此可以被解析到src/components/Button.js。

同时要注意该配置紧随其后的ModuleScopePlugin（webpack.config.js#L333-L347）：它禁止导入src/（及node_modules/）之外的文件。原因是 CRA 只对src/内的文件做 Babel 转译，绝对路径导入之所以被限制在src内，正是为了保证被导入文件一定经过了编译处理。

4.3 扩展名解析：导入时可省略文件后缀

文档示例中import Button from './Button'没有写.js后缀，这由 packages/react-scripts/config/paths.js 中的moduleFileExtensions保证，webpack 会按该顺序尝试补全扩展名：

const moduleFileExtensions = [ 'web.mjs', 'mjs', 'web.js', 'js', 'web.ts', 'ts', 'web.tsx', 'tsx', 'json', 'web.jsx', 'jsx', ];

值得注意的是 webpack.config.js#L319-L321 还做了过滤：项目未检测到tsconfig.json时，.ts/.tsx/web.ts*扩展名会被剔除，即纯 JS 项目不会尝试解析 TypeScript 文件，避免误匹配。

4.4 Jest 侧：modulePaths 与 moduleNameMapper

绝对导入在测试环境同样生效，实现见 packages/react-scripts/scripts/utils/createJestConfig.js#L55-L60：

modulePaths: modules.additionalModulePaths || [], moduleNameMapper: { '^react-native$': 'react-native-web', '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy', ...(modules.jestAliases || {}), },

其中additionalModulePaths即上一步得到的[src]，让 Jest 也能在src下解析裸路径导入；jestAliases则在baseUrl指向项目根目录时提供^src/(.*)$ → <rootDir>/src/$1的映射（modules.js#L86-L100），保证以src/开头的导入语句在测试中同样可达。

五、实践要点小结

结合文档与源码，可以归纳出以下可直接照做的清单：

1. 组件文件一律export default+import X from默认导入；多函数工具模块使用 named 导出；
2. 启用绝对导入：JS 项目创建根目录jsconfig.json，TS 项目修改tsconfig.json，在compilerOptions中设置"baseUrl": "src"，随后即可import Button from 'components/Button'；
3. baseUrl只能是src或node_modules，设为其他值项目会启动失败，这是 modules.js 的硬限制；
4. 不要同时保留tsconfig.json和jsconfig.json，getModules会直接抛出错误；
5. 导入路径不能越过src/：ModuleScopePlugin会拦截对src之外文件的导入（node_modules除外），需要引用外部文件时官方建议将其 link 进node_modules；
6. 导入语句可省略扩展名，webpack 与 Jest 都会按moduleFileExtensions顺序自动补全。

这套机制由 test/fixtures/jsconfig/index.test.js 覆盖的开发启动、生产构建与 Jest 测试三重验证，可以作为绝对路径导入在 CRA 中"开箱即用且行为一致"的直接证据。若需查阅jsconfig.json与tsconfig.json的完整字段参考，可以对照文档中指向的官方配置说明自行检索，CRA 只读取其中的compilerOptions.baseUrl一项。

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app