把一个传统的多页面项目迁移到服务端渲染框架时，最常见的报错莫过于ReferenceError: window is not defined。奇怪的是，同样的代码在浏览器里跑得好好的，一旦放进Node进程就立刻崩溃。这个异常的罪魁祸首往往不是业务代码本身，而是jQuery在模块加载阶段就偷偷访问了window对象。要彻底解决这个问题，光靠在网上抄一行if判断是不够的，需要先弄清楚jQuery的初始化机制。
一、从jQuery源码看异常的真正成因
打开jQuery的发布文件，在末尾可以看到一段工厂函数结构。jQuery采用了UMD的模块包装方式，代码大致如下：
(function(global, factory) {
// CommonJS 环境
if (typeof module === "object" && typeof module.exports === "object") {
module.exports = global.document
? factory(global, true)
: function(w) {
if (!w.document) {
throw new Error("jQuery requires a window with a document");
}
return factory(w);
};
} else {
factory(global);
}
})(typeof window !== "undefined" ? window : this, function(window, noGlobal) {
// jQuery 主体代码，大量使用 window 和 document
});注意最后那一行，jQuery在确定传入哪个全局对象时，会检查window是否存在。Node.js环境下不存在window，于是传入this（模块级作用域里等于exports，通常是空对象）。虽然模块本身不会立刻报错，但jQuery主体代码在初始化时会立即执行一系列操作，比如读取document.documentElement来初始化对浏览器的支持检测，缓存createElement方法等。这些操作在真实浏览器环境中瞬间完成，在Node中却直接命中undefined属性访问，抛出异常。
所以问题的本质是：jQuery是一个以浏览器为第一运行环境的库，它的初始化是急切式的，而SSR的首屏渲染发生在Node进程中，两者天然冲突。理解了这一点，就能明白为什么简单地把import语句挪个位置往往无效——只要模块被加载，初始化就会执行。
二、四种主流解决方案对比
方案一：延迟到客户端再初始化
最直接的办法是让jQuery只出现在浏览器侧。以Vue的Nuxt框架为例，可以通过插件配置禁止服务端执行：
// plugins/jquery.js
import $ from "jquery";
export default (context, inject) => {
inject("jq", $);
};
// nuxt.config.js
export default {
plugins: [
{ src: "~/plugins/jquery.js", mode: "client" }
]
};mode设为client后，这段插件代码只会在浏览器水合阶段执行，Node进程完全不会加载jQuery模块，异常自然消失。React的Next.js也有类似机制，用dynamic import配合ssr: false可以达到相同效果。这种方案的优点是改动小、见效快，缺点是所有依赖jQuery的逻辑都必须保证只在客户端生命周期里运行，如果组件的服务端渲染分支里不小心调用了$，问题会换个位置重新出现。
方案二：构造函数式引入，手动传入模拟window
如果确实需要在服务端操作DOM片段（比如解析HTML字符串），可以用jQuery提供的工厂模式，配合jsdom构造一个虚拟的浏览器环境：
const { JSDOM } = require("jsdom");
const { window } = new JSDOM("<!DOCTYPE html><html><body></body></html>");
const jQuery = require("jquery")(window);
// 现在可以在 Node 中使用 jQuery 解析 HTML
const $ = jQuery;
const title = $("<div class='item'>hello</div>").attr("class");
console.log(title); // itemrequire("jquery")在无window环境下返回的是一个包装函数，调用它并传入window实例，就能得到一份绑定了虚拟文档的jQuery。这个方案适合做HTML字符串的提取和清洗，但要注意jsdom的性能开销不小，不适合高并发场景，也不建议用它模拟完整浏览器行为。
方案三：条件判断加运行环境检测
对于必须同构执行的代码，可以在模块顶层加环境判断：
let $ = null;
if (typeof window !== "undefined") {
$ = require("jquery");
}
export function initTooltip() {
if (!$) return;
$(".js-tooltip").tooltip();
}这种写法利用了typeof对未声明变量不抛错的语言特性，在服务端让$保持为null，所有依赖它的函数内部先做空值保护。它的缺点是代码侵入性强，每个用到jQuery的地方都要防御一次，长期维护成本偏高，适合作为过渡方案或局部修补。
方案四：彻底去jQuery化
从架构角度讲，SSR项目里保留jQuery本身就是一种技术债。jQuery的核心价值是抹平浏览器差异和提供便捷的DOM API，而现代浏览器原生能力已经覆盖了大部分场景。document.querySelector、fetch、classList、closest等方法可以替换绝大多数jQuery调用。服务端渲染框架自带的数据流和生命周期，也让直接操作DOM的做法与框架的虚拟DOM机制相互冲突，容易出现水合后状态错乱。如果是长期维护的项目，建议逐步把jQuery插件替换为框架生态内的组件库，从根本上消除对window的依赖。
三、排查与预防的实战建议
实际排查时，报错堆栈往往指向webpack打包后的bundle文件，位置很难直接对应源码。这时可以借助webpack的externals配置，把jquery标记为外部依赖，让它在运行时require，堆栈信息会清晰很多。另一个技巧是在Node里全局搜索哪些文件静态import了jquery，找出所有触发加载的入口，逐一评估是否真的需要在模块顶层引入。
预防层面，建议在项目里建立一条规范：任何依赖浏览器全局变量（window、document、navigator、location）的模块，一律不允许出现在服务端会执行的代码路径中。可以配置ESLint的规则检测顶层window访问，或者在CI里跑一遍服务端渲染冒烟测试，让这类问题在合码前暴露。此外，引入第三方jQuery插件时特别要小心，很多老插件不仅自己访问window，还会在加载瞬间就执行初始化，即使主库做了隔离也会被插件拖垮。
最后需要提醒的是，解决异常不等于方案正确。用mode: client把jQuery藏到浏览器侧只是让报错消失，如果代码逻辑上仍依赖jQuery去修改服务端渲染出来的内容，就违背了SSR首屏直出的初衷。评估每个jQuery调用的真实必要性，能删则删，不能删的想清楚它应该在哪个环境、哪个生命周期里执行，这才是处理这类问题的正确思路。
jQuery SSRwindow is not defined服务端渲染修改时间：2026-09-15 19:28:36