Node.js SSR中import/require CSS必然失败，因无document等DOM API；正确做法是构建时用mini-css-extract-plugin提取CSS为文件，服务端读取其内容并内联到HTML head中。
Node.js服务端渲染中直接 import 或 require CSS 文件会报错，因为 Node 环境没有 document.createElement('style') 和 DOM API。这不是“没配好 Webpack”，而是环境本质不支持——必须把 CSS 处理逻辑从运行时移出。
为什么 import './style.css' 在 Node SSR 中必然失败
CSS 文件被 Webpack/ESBuild 处理时，默认生成的是浏览器端注入 <style> 标签的代码（如 __webpack_require__.i(css)），这类代码依赖 window、document，在纯 Node 环境执行直接抛 ReferenceError: document is not defined。即使你用 css-loader + style-loader，后者也只适用于客户端。
常见错误现象：
ReferenceError: document is not definedTypeError: Cannot read property 'appendChild' of null- Webpack 构建成功，但 Node 启动时报错，或 SSR 渲染时白屏
正确做法：分离 CSS 提取与注入时机
服务端不执行 CSS 注入逻辑，只负责把样式内容作为字符串提取出来，再拼进 HTML 的 <head> 里。关键在于「谁来提取」「何时注入」。
立即学习“前端免费学习笔记（深入）”；
OC SSH Tunnel Node Recovery
下载
诊断并恢复通过 SSH 隧道连接的 OpenClaw 节点。用于解决配对必需错误、隧道冲突、远程端点错误以及 SSH 目标配置错误等问题。
实操建议：
- Webpack 场景下，禁用
style-loader，改用mini-css-extract-plugin—— 它在构建时把 CSS 抽成独立文件（如main.css），Node 运行时只需读取该文件内容，不执行任何 DOM 操作 - Vite 场景下，启用
build.cssCodeSplit: false并配合ssr: { noExternal: ['your-ui-lib'] }，确保 CSS 被打包进服务端 bundle，再用正则或 AST 提取（不推荐，维护成本高） - 若用 CSS-in-JS（如 Emotion），必须启用其 SSR 支持：服务端调用
renderStylesToString()获取内联样式字符串，再注入到 HTML<head>中
React SSR 中注入 CSS 的最小可行代码
以 Webpack + mini-css-extract-plugin 为例，服务端需读取构建产出的 CSS 文件并塞进响应 HTML：
const fs = require('fs');
const cssContent = fs.readFileSync('./dist/main.css', 'utf8');
app.get('*', (req, res) => {
const html = ReactDOMServer.renderToString(<App />);
res.send(`
<!DOCTYPE html>
<html>
<head>
<style>${cssContent}</style>
</head>
<body><div id="root">${html}</div></body>
</html>
`);
});
注意点：
-
fs.readFileSync是阻塞调用，生产环境应提前读入内存缓存，避免每次请求都 IO - 若 CSS 文件含
@import或字体 URL，需确保路径在服务端可解析（推荐使用相对路径或 CDN 绝对路径） - 多个 chunk 的 CSS 需聚合处理，
mini-css-extract-plugin默认按 entry 分离，得通过stats.json或插件收集所有 CSS asset
容易忽略的兼容性细节
CSS 提取不是一劳永逸。几个真实项目中反复踩坑的点：
- 开发时用 HMR，CSS 是动态注入的；生产 SSR 必须关掉 HMR 相关 loader，否则构建产物仍含
style-loader逻辑 - Bootstrap-select 等 jQuery 插件自带 CSS，若通过
require('bootstrap-select/dist/css/bootstrap-select.min.css')引入，同样触发 Node 报错——应改为 CDN 链接或手动拷贝到 public 目录 - 服务端渲染的 CSS 必须是“确定性”的：不能依赖
window.innerWidth或用户代理做媒体查询切换，否则首屏样式和客户端 hydration 不一致
最稳妥的方式，是让所有样式都走构建时提取 + 字符串注入，彻底规避运行时 DOM 操作。哪怕多一次文件读取，也比在 Node 里模拟浏览器环境更可控。
