为什么我的自定义组件在SSR渲染后样式丢失了？

夏侯艺嘉提问于 2026-02-19 09:44:45 阅读 3

组件

我在用Vue 3开发一个自定义组件MyButton，服务端渲染后样式完全没生效，但客户端直出没问题。组件用了CSS Modules和动态类名，服务端返回的HTML里类名变成了_style_这样的占位符：


<button class="_style_ _button_active_">Click me</button>

我尝试过在vite.config.js里添加ssr: { noExternal: ['@styles'] }，也确认了服务端入口引入了全局样式表，但控制台报错：Cannot read properties of undefined (reading 'Button')。是不是CSS Modules在SSR时需要特殊处理？

我来解答赞 3 收藏

反馈

2 条解答

迷人的春凤 Lv1

这个问题的关键在于CSS Modules在服务端渲染时的处理方式。官方文档里提到，CSS Modules在SSR场景下需要额外的配置来确保样式能够正确注入。

首先，你在服务端返回的HTML里看到的_style_占位符，是因为服务端渲染时没有正确解析CSS Modules的映射关系。Vue 3的SSR机制默认不会自动处理CSS Modules的类名映射，所以需要手动干预。

解决方法如下：

1. 确保你的构建工具（比如Vite或Webpack）在服务端和客户端都启用了CSS Modules的支持，并且两者的配置保持一致。以Vite为例，你可以在vite.config.js中添加对CSS Modules的支持：

export default {

  css: {

    modules: {

      localsConvention: 'camelCase',

      generateScopedName: '[name]__[local]--[hash:base64:5]'

    }

  },

  ssr: {

    noExternal: ['your-css-module-package-name']

  }

}

2. 在服务端入口文件中，显式引入组件的样式文件。如果你使用的是动态导入的方式，可能会导致服务端无法正确解析样式。建议改为静态导入，比如：

import MyButton from './MyButton.vue'
import styles from './MyButton.module.css'

3. 修改你的组件代码，确保在服务端和客户端都能正确解析类名。可以用一个包装函数来处理样式对象：

import styles from './MyButton.module.css'



export default {

  props: {

    isActive: Boolean

  },

  computed: {

    buttonClass() {

      return {

        [styles.button]: true,

        [styles.active]: this.isActive

      }

    }

  }

}

最后，关于报错Cannot read properties of undefined (reading 'Button')，这通常是因为样式模块没有正确导出。检查一下你的样式文件命名是否符合CSS Modules的约定，比如文件名应该以.module.css结尾。

总结一下，核心问题就是服务端没有正确解析CSS Modules的映射关系。按照上面的方法调整后，服务端返回的HTML应该就能包含正确的类名了。如果还有问题，记得检查一下服务端和客户端的样式哈希值是否一致，不一致会导致样式闪动或者丢失。

2026-02-19 17:13

子硕~ Lv1

这个问题确实是CSS Modules在SSR下的典型坑。省事的话，直接在vite.config.js里加个配置就行：

css: {

  modules: {

    localsConvention: 'camelCase',

    generateScopedName: '[local]_[hash:base64:5]'

  }

}

另外记得在服务端入口文件里同步加载样式，比如 import styles from './MyButton.module.css'，别用动态import。控制台那个undefined报错就是样式没正确导出导致的。

2026-02-19 10:01