React项目部署Netlify/Vercel报无法解析Navbar模块错误如何解决

报错现象 #

在Netlify、Vercel平台部署React项目时，均抛出如下构建错误：

Module not found: Error: Can't resolve './components/layouts/Navbar' in '/opt/build/repo/src'

对应App.jsx中的业务代码如下：

// import Navbar from "./components/layouts/Navbar";
import Navbar from "./components/layouts/Navbar"
import Footer from "./components/layouts/Footer";
import Alert from "./components/layouts/Alert";
import Home from "./pages/Home";
import User from "./pages/User";
import About from "./pages/About";
import NotFound  from "./pages/NotFound";
import { GitHubProvider } from "./components/context/github/GithubContext";
import { AlertProvider } from "./components/context/alert/AlertContext";

function App() {
  return (
    <GitHubProvider>
      <AlertProvider>
        <Router>
          <div className="flex flex-col justify-between h-screen ">
            <Navbar />
            <main className="container mx-auto px-3 pb-12">
              <Alert />
              <Routes>
                <Route path="/" element={<Home />} />
                <Route path="/about" element={<About />} />
                <Route path="/user/:login" element={<User />} />
                <Route path="/notfound" element={<NotFound />} />
                <Route path="/*" element={<NotFound />} />
              </Routes>
            </main>
            <Footer />
          </div>
        </Router>
      </AlertProvider>
    </GitHubProvider>
  );
}

export default App;

核心原因 #

该问题和部署平台本身无关，是本地开发环境与线上构建环境的文件系统规则差异导致：Windows、macOS默认使用大小写不敏感的文件系统，本地开发时即使文件名/路径大小写和导入语句不匹配也能正常运行；但Netlify、Vercel的构建机均使用Linux系统，严格区分文件名、路径的大小写，只要存在大小写不匹配就会抛出模块找不到的错误。

排查解决步骤 #

• 核对文件路径与文件名的大小写完全匹配
  打开本地项目的src/components/layouts/目录，逐一核对：
  • 路径中的文件夹名完全一致：确认目录名是layouts，不是Layouts、layout等拼写/大小写有差异的名称
  • 目标文件名完全一致：确认目录下的导航组件文件名为Navbar.js/Navbar.jsx/Navbar.tsx（和你实际使用的文件后缀匹配），不是navbar.jsx、NavBar.jsx、Navabar.jsx这类存在大小写或拼写错误的名称
• 排查Git大小写缓存问题
  如果本地文件名和导入语句完全匹配，但线上依然报错，大概率是Git默认忽略文件名大小写变更，导致你之前修改文件名大小写的操作没有被同步到远程仓库。执行以下命令修复即可：

  # 开启Git文件名大小写敏感校验
  git config core.ignorecase false
  # 临时重命名文件提交，再改回正确名称提交，强制Git识别文件名变更
  git mv src/components/layouts/Navbar.jsx src/components/layouts/temp_nav.jsx
  git commit -m "fix: temp rename nav component"
  git mv src/components/layouts/temp_nav.jsx src/components/layouts/Navbar.jsx
  git commit -m "fix: correct nav component filename case"
  git push
  

• 本地预构建校验
  修复完成后先在本地执行npm run build或yarn build，如果本地构建能正常通过，再推送代码到远程仓库触发线上部署，避免反复提交排查。

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