Next.js应用部署后CSS样式无法加载的问题排查（Vercel/GitHub Pages）

一、通用排查点 #

• 检查next.config.js配置：GitHub Pages必须设置basePath为你的仓库名（比如basePath: '/your-repo-name'）；Vercel一般无需额外配置，但自定义域名场景下要确认assetPrefix无错误。
• 确认样式文件路径：SCSS导入用相对路径，避免绝对路径（比如把/styles/xxx.scss改成../styles/xxx.scss）；Styled Components要保证babel配置正确。

二、SCSS方案修复 #

1. GitHub Pages部署 #

• 确保next.config.js开启SCSS支持并配置静态导出：

/** @type {import('next').NextConfig} */
const nextConfig = {
  basePath: '/your-repo-name', // 替换为你的GitHub仓库名
  output: 'export', // 适配GitHub Pages的静态导出模式
  sassOptions: {
    includePaths: ['./styles'],
  },
}

module.exports = nextConfig

• 执行npm run build生成out目录后，检查out/_next/static/css下是否存在编译后的CSS文件，确认构建产物完整。

2. Vercel部署 #

• 无需额外配置basePath（自定义域名除外），但要保证next.config.js的SCSS配置正确，且package.json的build命令为next build。
• 检查Vercel构建日志，确认SCSS编译无报错，若提示缺少依赖，执行npm install sass补全依赖。

三、Styled Components方案修复 #

1. 基础配置检查 #

• 安装必要依赖：npm install styled-components babel-plugin-styled-components
• 在项目根目录创建babel.config.js，配置如下：

module.exports = {
  presets: ['next/babel'],
  plugins: [['styled-components', { ssr: true }]],
}

• 配置_document.tsx（或_document.js）实现服务端渲染样式收集：

import Document, { Html, Head, Main, NextScript } from 'next/document'
import { ServerStyleSheet } from 'styled-components'

export default class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const sheet = new ServerStyleSheet()
    const originalRenderPage = ctx.renderPage

    try {
      ctx.renderPage = () =>
        originalRenderPage({
          enhanceApp: (App) => (props) => sheet.collectStyles(<App {...props} />),
        })

      const initialProps = await Document.getInitialProps(ctx)
      return {
        ...initialProps,
        styles: (
          <>
            {initialProps.styles}
            {sheet.getStyleElement()}
          </>
        ),
      }
    } finally {
      sheet.seal()
    }
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

2. 平台适配 #

• GitHub Pages：同样需要设置basePath和output: 'export'，静态导出后检查out目录下的HTML文件是否包含Styled Components生成的<style>标签。
• Vercel：平台会自动识别babel配置，只需确认构建日志中styled-components插件已正常加载。

四、其他排查方向 #

• .gitignore检查：你当前的配置忽略/.next/和/out/是正确的，平台会重新构建生成产物，不影响部署。
• 缓存问题：除清理缓存外，用无痕模式访问或强制刷新（Ctrl+Shift+R / Cmd+Shift+R）验证。
• 项目结构：由于缺少项目结构图片，需确认样式文件存放路径正确，组件导入路径无拼写错误。

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