如何在 Next.js 中配置 PostCSS

默认行为

Next.js 使用 PostCSS 编译其内置 CSS 支持所需的样式文件。

在无配置的情况下，Next.js 默认会对 CSS 应用以下转换：

• Autoprefixer 自动为 CSS 规则添加浏览器前缀（兼容至 IE11）。
• 修复 跨浏览器 Flexbox 错误以符合规范标准。
• 自动编译新 CSS 特性以实现 IE11 兼容：
  • all 属性
  • Break 属性
  • font-variant 属性
  • Gap 属性
  • 媒体查询范围

默认情况下，CSS 网格布局和自定义属性（CSS 变量）不会为 IE11 进行编译。

如需为 IE11 编译 CSS 网格布局，可在 CSS 文件顶部添加以下注释：

/* autoprefixer grid: autoplace */

也可以通过下方折叠的配置（见下文"自定义插件"章节）全局启用项目对 IE11 的 CSS 网格布局支持。

{
  "plugins": [
    "postcss-flexbugs-fixes",
    [
      "postcss-preset-env",
      {
        "autoprefixer": {
          "flexbox": "no-2009",
          "grid": "autoplace"
        },
        "stage": 3,
        "features": {
          "custom-properties": false
        }
      }
    ]
  ]
}

CSS 变量不会被编译，因为无法安全实现。如需使用变量，建议改用 Sass 变量，它们会被 Sass 编译处理。

自定义目标浏览器

Next.js 允许通过 Browserslist 配置目标浏览器（用于 Autoprefixer 和 CSS 特性编译）。

在 package.json 中添加 browserslist 键即可自定义：

{
  "browserslist": [">0.3%", "not dead", "not op_mini all"]
}

可通过 browsersl.ist 工具可视化查看目标浏览器范围。

CSS 模块

无需配置即可支持 CSS 模块。将文件后缀改为 .module.css 即可启用 CSS 模块功能。

了解更多关于 Next.js 的 CSS 模块支持。

自定义插件

警告：当自定义 PostCSS 配置文件时，Next.js 会完全禁用默认行为。需手动配置所有需要的编译特性，包括 Autoprefixer，并手动安装配置中的插件（例如 npm install postcss-flexbugs-fixes postcss-preset-env）。

在项目根目录创建 postcss.config.json 文件即可自定义 PostCSS 配置：

{
  "plugins": [
    "postcss-flexbugs-fixes",
    [
      "postcss-preset-env",
      {
        "autoprefixer": {
          "flexbox": "no-2009"
        },
        "stage": 3,
        "features": {
          "custom-properties": false
        }
      }
    ]
  ]
}

须知：Next.js 也支持使用 .postcssrc.json 文件名，或从 package.json 的 postcss 键读取配置。

也可以通过 postcss.config.js 进行配置，这在需要根据环境动态加载插件时非常有用：

module.exports = {
  plugins:
    process.env.NODE_ENV === 'production'
      ? [
          'postcss-flexbugs-fixes',
          [
            'postcss-preset-env',
            {
              autoprefixer: {
                flexbox: 'no-2009',
              },
              stage: 3,
              features: {
                'custom-properties': false,
              },
            },
          ],
        ]
      : [
          // 开发环境不应用转换
        ],
}

须知：Next.js 也支持使用 .postcssrc.js 文件名。

不要使用 require() 导入 PostCSS 插件，插件必须以字符串形式提供。

须知：如果 postcss.config.js 需要同时支持其他非 Next.js 工具，需改用以下兼容的对象格式：

module.exports = {
  plugins: {
    'postcss-flexbugs-fixes': {},
    'postcss-preset-env': {
      autoprefixer: {
        flexbox: 'no-2009',
      },
      stage: 3,
      features: {
        'custom-properties': false,
      },
    },
  },
}