如何在 React.js 中使用 @ 符号进行路径别名导入

在 react（如 next.js）项目中，import config from “@config/config.json” 这类以 @ 开头的导入语法是通过配置路径别名（path aliases）实现的，需在 jsconfig.json（开发环境）或 tsconfig.json（typescript 项目）中设置 baseurl 和 paths。

这种 @ 前缀本质上是模块解析路径别名（Module Path Alias），并非 webpack 或 vite 原生语法，而是由构建工具（如 Next.js、Vite、Create react app v5+）基于 typescript/javaScript 配置文件自动识别并支持的特性。

✅ 正确配置步骤（以 Next.js/React 为例）

1. 在项目根目录创建 jsconfig.json（若使用 TypeScript，则用 tsconfig.json，二者配置结构一致）
2. 配置 baseUrl 和 paths 映射规则：

{   "compilerOptions": {     "baseUrl": ".",     "paths": {       "@config/*": ["config/*"],       "@src/*": ["src/*"],       "@components/*": ["src/components/*"],       "@utils/*": ["src/utils/*"]     }   },   "include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"],   "exclude": ["node_modules"] }

? 注意：”baseUrl”: “.” 表示所有别名路径都相对于项目根目录解析；”@config/*” 将匹配 import x from “@config/xxx”，并映射到 ./config/xxx。

3. 确保目录结构匹配
   例如，若你写 import theme from “@config/theme.json”，则项目中必须存在：

   your-project/ ├── jsconfig.json ├── config/ │   ├── config.json │   └── theme.json   ← 此文件将被正确解析

⚠️ 常见注意事项

• Next.js 13+ 默认支持 jsconfig.json / tsconfig.json 路径别名，无需额外插件；但需重启开发服务器（next dev）使配置生效。

• Create React App（CRA）v5+ 也支持，但旧版本需 craco 或 react-app-rewired 手动配置 Webpack。

• Vite 用户：需在 vite.config.ts 中显式配置 resolve.alias（jsconfig.json 不生效）：

  import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'path';  export default defineConfig({   plugins: [react()],   resolve: {     alias: {       '@config': path.resolve(__dirname, 'config'),       '@src': path.resolve(__dirname, 'src')     }   } });

• 编辑器支持：VS Code 依赖 jsconfig.json 提供跳转与自动补全；若无响应，请检查文件位置是否为项目根目录，并重启 TS 服务（Ctrl/Cmd + Shift + P → “TypeScript: Restart TS server”）。

✅ 最佳实践建议

• 使用语义化别名（如 @config、@types、@assets），避免过度泛化（如 @/*）；
• 在团队项目中，将常用别名写入文档或 README，提升可维护性；
• 避免别名与 node_modules 中真实包名冲突（例如不要定义 @react —— 它已是官方 scoped package）。

通过合理配置路径别名，你不仅能告别冗长相对路径（如 ../../../config/theme.json），还能显著提升代码可读性与重构安全性。