部署NextJS项目到自有服务器执行npm run build提示模块未找到错误

开发的NextJS项目需要部署到运行AlmaLinux 8的预发布测试服务器，服务器已安装Node 16.8.0。将项目全量复制到服务器后执行npm run build命令，触发类型错误，提示无法找到TopHeader组件模块。

build
> next build

info  - Loaded env from /var/www/html/CrashCatch/CrashCatchDocs_Testing/.env
Failed to compile.

./pages/[...].tsx:2:23
Type error: Cannot find module '../components/TopHeader' or its corresponding type declarations.

  1 | import Head from 'next/head'
> 2 | import TopHeader from "../components/TopHeader";
    |                       ^
  3 | import Link from 'next/link'
  4 | import {useRouter} from "next/router";
  5 | import {getSlugFromUrl} from "../JSFuncs/HelperFunctions";

项目目录结构 #

./pages/[...].tsx核心代码 #

import Head from 'next/head'
import {getSlugFromUrl} from "../JSFuncs/HelperFunctions";
import UserHelpContainer from "../components/Articles/UserHelpContainer";
import UserSidebar from "../components/Sidebar/UserSidebar";
import useArticle from "../hooks/useArticle";
import {useEffect, useState} from "react";
import useCrashCatch from "../hooks/useCrashCatch";
import TopHeader from "../components/TopHeader";

export default function Home() {

    const slug = getSlugFromUrl();
    const {loading, publishedArticle, errors, refetch} = useArticle(slug);
    const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
    const {crashcatch} = useCrashCatch('12345', "123456", "1.0.0");
    useEffect(() => {
        (
            async function() {
                await refetch();
            }
        )();

    }, [slug]);

    return (
        <>
            <div className="w-full h-full min-h-full overflow-none absolute">
                <Head>
                    <title>Crash Catch Documentation</title>
                    <link rel="icon" href="/favicon.ico" />
                    <meta name='description' content={publishedArticle !== null && typeof publishedArticle !== typeof undefined ? publishedArticle.metaDescription : ''} />
                    <meta name='keywords' content={publishedArticle !== null && typeof publishedArticle !== typeof undefined ? publishedArticle.metaKeywords : ''} />
                </Head>
                <TopHeader mobileSidebarOpen={mobileSidebarOpen} setMobileSidebarOpen={setMobileSidebarOpen} />
                <div className='flex flex-row h-full overflow-y-scroll'>
                    <UserSidebar slug={slug} mobileSidebarOpen={mobileSidebarOpen} setMobileSidebarOpen={setMobileSidebarOpen} />
                    <UserHelpContainer slug={slug} loading={loading} errors={errors} article={publishedArticle} />
                </div>
            </div>
        </>

    )
}

TopHeader组件声明代码 #

const TopHeader = React.memo(function TopHeader(props: TopNavProps)

1. 文件名大小写不匹配：本地开发环境（Windows/macOS）对文件名大小写不敏感，而AlmaLinux属于Linux系统，对文件名大小写高度敏感。如果本地TopHeader组件的实际文件名大小写和导入语句不一致，本地运行无异常，部署到服务器后就会找不到对应模块，这是此类跨环境部署问题最常见的诱因。
2. 文件缺失或路径错误：项目复制到服务器的过程中漏传了TopHeader对应的组件文件，或者文件存放路径和本地不一致，导致导入路径失效。
3. 组件导出规则错误：TopHeader组件没有使用export default做默认导出，或者导出名称和导入名称不匹配。
4. TypeScript解析配置异常：项目根目录tsconfig.json中的模块解析规则配置错误，或者没有配置对应可识别的文件扩展名，导致TypeScript无法识别组件文件。

• 登录服务器进入项目components目录，执行ls命令查看文件列表，确认TopHeader组件的文件名大小写和导入语句../components/TopHeader完全一致，不一致的话修改文件名或者导入语句的大小写即可。
• 确认TopHeader组件文件存在，且文件扩展名是.tsx/.ts等可被识别的格式，若扩展名不在默认解析列表中，可以在导入时补全扩展名，比如import TopHeader from "../components/TopHeader.tsx"。
• 检查TopHeader组件文件末尾是否有export default TopHeader导出语句，缺失的话补充即可。
• 检查项目根目录的tsconfig.json，确认compilerOptions下配置了"moduleResolution": "node"，保证路径解析规则符合Node标准。
• 若以上排查都无问题，删除项目下的node_modules目录、package-lock.json文件，重新执行npm install安装依赖后再运行npm run build即可。

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