Next.js部署Vercel报错SassError: 无法找到待导入样式表

问题复现 #

• 项目本地开发可正常运行，部署至Vercel时编译失败，抛出如下错误：

  SassError: Can't find stylesheet to import
  

• 错误指向styles/app.scss第14行@import "pages/Haveproject.module.scss"语句
• 现有代码逻辑：
  • pages/_app.js中全局引入../styles/globals.scss与../styles/app.scss
  • app.scss内按顺序引入abstracts目录下的variables.scss、mixins.scss，components目录下的Header.module.scss、Footer.module.scss，pages目录下的Home.module.scss、Haveproject.module.scss
• 已尝试移除导入路径前的./前缀，直接写裸路径@import "pages/Haveproject.module.scss"，问题未解决。

核心原因 #

1. 路径写法错误：Sass导入文件默认优先匹配相对路径，未加相对路径前缀的裸路径会默认从node_modules目录、以及用户配置的sassOptions.includePaths目录下查找文件，未配置全局路径的前提下，直接写pages/xxx不会读取项目根目录下的pages文件夹，自然找不到对应文件。
2. 文件系统大小写敏感差异：Vercel部署环境为Linux系统，文件系统严格区分大小写；本地开发使用的Windows/macOS默认大小写不敏感，哪怕文件名和导入语句的大小写有偏差本地也能正常加载，部署时会直接报找不到文件。
3. 路径层级计算错误：如果app.scss位于styles目录下，要访问同级目录的pages文件夹下的文件，需要先跳出styles目录到项目根目录，缺少../前缀的路径会被解析为styles/pages/Haveproject.module.scss，该路径实际不存在。

修复步骤 #

1. 修正所有导入语句的相对路径
   按照项目实际目录结构写全相对路径，标准Next.js目录结构下，styles/app.scss导入其他目录scss的正确写法示例：

   // styles目录下的子目录文件，用./前缀访问当前目录下的子路径
   @import "./abstracts/variables.scss";
   @import "./abstracts/mixins.scss";
   @import "./components/Header.module.scss";
   @import "./components/Footer.module.scss";
   // pages目录和styles目录同级，需要用../跳出当前styles目录到根目录再访问
   @import "../pages/Home.module.scss";
   @import "../pages/Haveproject.module.scss";
   

2. 全量校验文件名、文件夹名大小写
   逐个核对每个导入的scss文件、所在文件夹的实际命名，确保和import语句中的大小写完全一致，比如实际文件名为haveProject.module.scss就不能写成Haveproject.module.scss，实际文件夹名为Components就不能写成components。
3. （可选）配置全局Sass加载路径简化写法
   如果不想每次写多层相对路径，可以在项目根目录的next.config.js中添加Sass全局加载路径配置：

   const path = require('path')
   /** @type {import('next').NextConfig} */
   const nextConfig = {
     sassOptions: {
       includePaths: [path.join(__dirname, 'styles'), __dirname],
     },
   }
   module.exports = nextConfig
   

   配置完成后，无需写相对前缀，直接写@import "abstracts/variables.scss"、@import "pages/Haveproject.module.scss"即可正常识别文件，提交代码重新部署即可生效。
4. 样式引入规范修正
   带.module.scss后缀的是CSS Module文件，设计目的是组件级样式隔离，不建议全局导入到公共scss文件中，否则会丢失哈希作用域导致样式污染。正确做法是在对应的页面、组件文件中单独引入对应的module.scss文件，全局公共样式、变量、mixin放在不带.module后缀的普通scss文件中全局引入。

内容的提问来源于stack exchange，提问作者Rahil Əliyev