你有没有遇到过这种情况：本地运行完美的Next.js应用，一部署到Netlify就出现满屏红色错误提示：

Module not found: Can't resolve '@/components/Button'

别担心，这不是你的代码问题。

我在部署Sellexa（一个面向少数群体创业者的社交电商平台）时也遇到了同样的问题。后来发现，问题不在于代码本身，而在于环境如何处理路径别名和大小写敏感度。

让我们来详细分析这个问题。

为什么会出现这个错误

这个错误通常意味着两种情况之一：

1. 本地环境很宽容，但Netlify环境很严格
   macOS和Windows使用不区分大小写的文件系统，但Netlify的Linux服务器是区分大小写的。

所以：

import Button from "@/components/ui/button";

即使你的文件名是Button.tsx，在本地也能正常工作。

但在Netlify上会失败，因为button ≠ Button。

2. 构建时没有配置别名（@）
   很多Next.js入门教程假设你的编辑器或TypeScript能自动理解@的含义。

但除非你明确告诉TypeScript和webpack，否则Netlify的构建系统不知道如何解析它。

解决方案

按照下面四个步骤操作，你就不会再看到这个错误了。

第一步：在tsconfig.json中添加路径配置

在项目根目录，打开（或创建）tsconfig.json文件：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

这告诉TypeScript和你的IDE，@指的是你的/src文件夹。

第二步：在next.config.mjs中添加Webpack别名

Next.js在生产构建期间仍然需要理解这个别名。

打开next.config.mjs文件，添加以下代码：

import path from "node:path";

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...(config.resolve.alias ?? {}),
      "@": path.resolve(process.cwd(), "src"),
    };
    return config;
  },
};

export default nextConfig;

现在@在本地和Netlify上都能正确解析了。

第三步：确保文件和导入语句的大小写一致

在Linux系统中，Button.tsx和button.tsx是不同的文件。

运行这个命令来检查你的导入语句：

git grep -i "@/components"

确保你的导入语句大小写与文件名完全一致。

第四步：清除缓存并重新部署

在Netlify上：

进入你的站点 → 部署

点击"触发部署" → "清除缓存并部署站点"

修复别名后的干净构建应该会立即成功。

额外提示：如果你在使用Supabase时遇到这个问题

如果你的日志显示：Module not found: Can't resolve '@/integrations/supabase/client'

这只是意味着缺少client.ts文件。

正确的文件结构应该是：

src/
  integrations/
    supabase/
      client.ts

client.ts文件内容：

import { createClient } from "@supabase/supabase-js";

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

快速总结

经验教训

Linux对文件大小写要求很严格。

你的IDE可能能"看到"@/路径，但除非配置了，否则Webpack看不到。

始终在tsconfig.json和next.config.mjs中都定义别名。

CI/CD问题通常与环境有关，而不是代码问题。

其他可能的问题和解决方案

如果你使用的是JavaScript而不是TypeScript，需要在jsconfig.json中进行配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

如果你使用其他构建工具，比如Vite，配置方式会有所不同：

// vite.config.js
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

预防措施

为了以后避免这类问题，建议：

1. 在项目初始化时就配置好路径别名

2. 使用统一的命名规范（推荐kebab-case：button.tsx）

3. 在团队中建立代码规范，确保所有人使用相同的导入方式

4. 在CI/CD流程中加入大小写检查

实际案例

有个开发者在部署时遇到了这个错误，花了几个小时检查文件是否存在。最后发现只是因为在导入时写了：

import Button from "@/components/button"

但实际文件名是Button.tsx。

将导入语句改为：

import Button from "@/components/Button"

问题就解决了。

最后建议

当我第一次遇到这个问题时，我浪费了好几个小时寻找实际上并不缺失的文件。

next.config.mjs中的一行代码就解决了一切。

如果你也面临同样的问题，直接复制这些配置，可以省去很多麻烦。

下次你的Netlify构建出现红色错误时，你就知道该怎么做了。

记住，这类部署问题很常见，特别是当开发环境和生产环境使用不同操作系统时。提前配置好路径别名和保持大小写一致，可以避免很多不必要的麻烦。