React Vite引入页面组件时无法识别，报模块解析失败错误

在向页面组件中添加自定义组件时，持续遇到上述导入错误，尝试添加其他组件也会触发相同问题。

页面组件代码（HomePage.tsx） #

import Header from "~src/ui/components/organisms/Header/Header";
import $ from "./HomePage.module.scss";

const HomePage: React.FunctionComponent = () => {
  document.title = "Home";

  return (
    <>
      <div className={$.wrapper}>
        <Header type="home" />
      </div>
    </>
  );
};

export default HomePage;

Header组件代码（Header.tsx） #

import Navbar from "../../molecules/Navbar/Navbar";
import HeaderMainContent from "../../molecules/HeaderMainContent/HeaderMainContent";
import HeaderDetailContent from "../../molecules/HeaderDetailContent/HeaderDetailContent";

import $ from "./Header.module.scss";

type Props = {
  type: "home" | "detail";
};

const Header = ({ type }: Props) => {
  return (
    <header className={`${type === "home" ? $.header_long : $.header_short}`}>
      <div className={$.wrapper}>
        <Navbar type={type === "home" ? "home" : "detail"} />
        {type === "home" && <HeaderMainContent />}
        {type === "detail" && <HeaderDetailContent />}
      </div>
    </header>
  );
};

export default Header;

文件夹结构 #

src/
├── ui/
│   ├── components/
│   │   ├── organisms/
│   │   │   └── Header/
│   │   │       ├── Header.tsx
│   │   │       └── Header.module.scss
│   │   └── molecules/
│   │       ├── Navbar/
│   │       │   ├── Navbar.tsx
│   │       │   └── Navbar.module.scss
│   │       ├── HeaderMainContent/
│   │       │   ├── HeaderMainContent.tsx
│   │       │   └── HeaderMainContent.module.scss
│   │       └── HeaderDetailContent/
│   │           ├── HeaderDetailContent.tsx
│   │           └── HeaderDetailContent.module.scss
└── pages/
    └── HomePage/
        ├── HomePage.tsx
        └── HomePage.module.scss

解决方案 #

• 校验路径别名配置：确认~src别名已在项目打包工具（Webpack/Vite）或TypeScript配置中正确设置。比如在tsconfig.json的compilerOptions.paths里添加：

  "paths": {
    "~src/*": ["src/*"]
  }
  

  Vite项目需在vite.config.ts的resolve.alias中配置：

  import { defineConfig } from 'vite'
  import path from 'path'
  
  export default defineConfig({
    resolve: {
      alias: {
        '~src': path.resolve(__dirname, 'src')
      }
    }
  })
  

• 检查文件路径与大小写：确认导入的文件实际存在，且文件名大小写和导入语句一致（部分系统区分大小写，比如Linux/macOS）。

• 验证相对导入路径：Header组件中../../molecules/Navbar/Navbar这类相对路径需确认层级正确，确保目标文件位置无误。

• 清理缓存并重启服务：重启开发服务器，清理打包工具缓存（如Vite的.vite文件夹、Webpack的node_modules/.cache），避免缓存导致的解析异常。

• 补充文件扩展名：若打包工具未配置自动补全tsx/jsx扩展名，尝试在导入时添加完整扩展名，比如import Header from "~src/ui/components/organisms/Header/Header.tsx"。

内容的提问来源于stack exchange，提问作者Meesie2109