You need to enable JavaScript to run this app. Vue服务端渲染:在.vue文件添加样式时报beforeCreate钩子document未定义错误
优惠活动
大模型
产品
解决方案
定价
更多

Vue服务端渲染:在.vue文件添加样式时报beforeCreate钩子document未定义错误

问题现象

在基于Vue的服务端渲染项目中,只要给.vue单文件组件添加<style>样式块,就会在服务端渲染的beforeCreate生命周期阶段抛出错误:

[Vue warn]: Error in beforeCreate hook: "ReferenceError: document is not defined"

项目架构对齐官方Vue SSR参考实现,未添加样式块时所有渲染流程完全正常。

核心根因

样式加载规则配置错误

当前webpack基础配置中,针对css、scss文件的处理规则同时加载了vue-style-loader和style-loader,二者存在功能重叠:

  • style-loader 的运行逻辑是代码执行时直接操作全局document对象插入内联样式标签,完全不兼容Node.js服务端环境
  • 服务端运行时不存在document全局对象,执行到这部分逻辑时就会直接抛出ReferenceError

双端样式规则未做环境隔离

当前样式规则是客户端、服务端构建共用的通用配置,没有针对Node.js服务端场景裁剪带DOM操作的loader:

  • 客户端构建场景只需要vue-style-loader(内置SSR兼容逻辑,不会在服务端执行DOM操作)即可完成样式注入
  • 服务端构建场景不需要执行任何样式注入逻辑,原本就不该引入会操作DOM的样式loader
修复方案
  1. 清理通用样式规则中的冗余loader
    从基础webpack配置的通用样式规则中完全移除style-loader,仅保留通用的样式解析loader:

    // 修正后的通用样式规则(双端共用)
    {
      test: /\.css$/,
      use: ['css-loader'],
    },
    {
      test: /\.scss$/,
      use: ['css-loader', 'sass-loader']
    }
    
  2. 为客户端构建配置追加专属样式注入规则
    在客户端构建的webpack配置中,单独追加仅在浏览器环境执行的样式注入loader:

    // 客户端配置内追加的规则
    rules: [
      {
        test: /\.css$/,
        use: ['vue-style-loader', 'css-loader']
      },
      {
        test: /\.scss$/,
        use: ['vue-style-loader', 'css-loader', 'sass-loader']
      }
    ]
    
  3. 修正服务端构建的externals匹配规则
    原配置中的nodeExternals白名单正则存在字符类匹配逻辑错误,会把|当成普通字符参与匹配,无法正确识别css、scss类文件,修正为正确的后缀匹配规则:

    externals: nodeExternals({
      allowlist: /\.(css|scss)$/
    })
    
  4. 验证效果
    调整完成后,服务端打包生成的server-bundle中不再包含操作document的样式注入代码,服务端渲染流程不会再触发document is not defined报错,样式会通过客户端manifest映射的资源在浏览器端正常加载。


内容的提问来源于stack exchange,提问作者yasuda_t

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.18 21:06:03