Next 14中使用CSS Modules结合linear-gradient无法显示背景图

问题核心：添加linear-gradient渐变叠加后背景图消失，单独使用背景图URL可正常显示。

排查与解决方案 #

1. 检查CSS变量格式与定义 #

你用到的--color-primary-light和--color-primary-dark必须是逗号分隔的RGB数值（如255, 100, 50），不能是十六进制（如#ff6432）或其他格式。如果变量未定义或格式错误，rgba()会解析失效，导致渐变层异常，进而遮挡或使背景图无法正常加载。

修复示例：

在header.module.css顶部或全局样式文件（如globals.css）中正确定义变量：

/* header.module.css */
:root {
  --color-primary-light: 131, 96, 251; /* 替换为你的实际浅色RGB值 */
  --color-primary-dark: 88, 28, 135;    /* 替换为你的实际深色RGB值 */
}

.header {
  height: 85vh;
  background-image: linear-gradient(
      to right bottom,
      rgba(var(--color-primary-light), 0.8),
      rgba(var(--color-primary-dark), 0.8)
    ),
    url('/img/hero-small.jpg');
  background-size: cover;
  background-position: top;
  position: relative;
}

2. 临时替换变量为具体值验证 #

如果不确定变量问题，可直接将渐变中的var()替换为具体RGB值，快速排查：

.header {
  height: 85vh;
  background-image: linear-gradient(
      to right bottom,
      rgba(131, 96, 251, 0.8),
      rgba(88, 28, 135, 0.8)
    ),
    url('/img/hero-small.jpg');
  background-size: cover;
  background-position: top;
  position: relative;
}

若此代码生效，说明原变量定义存在问题，需调整变量格式或位置。

3. 确认全局样式引入（若变量定义在全局） #

如果变量定义在globals.css中，需确保在layout.tsx中正确引入全局样式：

// app/layout.tsx
import './globals.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

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