CommonJS在轻量级SSR框架中通过动态import()、打包器externals配置及框架server-only机制，隔离Node原生模块，避免客户端误打包并确保服务端正确加载。
CommonJS 在轻量级 SSR 框架中管理服务端特有模块依赖，核心是**避免在客户端打包中混入 Node.js 原生模块（如 fs、path、crypto），同时确保服务端运行时能正确解析和加载这些模块**。这需要从模块引入方式、构建配置、运行时条件隔离三方面协同处理。
用动态 import() + 服务端判断隔离敏感模块
静态 require() 或 import 会被打包工具（如 Vite、esbuild）提前分析，容易将服务端模块误打入客户端包。推荐改用运行时动态导入，并配合环境判断：
- 只在服务端上下文（如 Express 的 request handler、SvelteKit 的
server.ts、Remix 的loader）中调用await import('fs') - 利用框架提供的运行时标识，例如：
if (typeof window === 'undefined') { await import('fs'); }
或更可靠的方式：检查process?.env?.SSR === 'true'（需构建时注入） - 注意：Node.js 14+ 支持动态
import()加载 CommonJS 模块，但返回的是命名空间对象（default属性可能为空），建议用import('fs').then(m => m.default || m)兼容
配置打包器排除服务端模块（externals）
轻量级 SSR 框架（如 SvelteKit、Astro、SolidStart）底层多基于 Vite 或 esbuild。需显式告诉打包器哪些模块不打包进客户端产物：
- Vite 中，在
vite.config.ts的ssr.external列表里声明：ssr: { external: ['fs', 'path', 'os', 'crypto', 'stream'] } - esbuild 用户可在
build配置中设置platform: 'node'的 target，并用external排除 - 关键点：
external只影响打包阶段，不改变运行时行为；它让打包器跳过这些模块的解析和嵌入，保留原生 require 调用
按需封装服务端能力为可树摇的工具函数
直接散落 require('fs') 容易失控。建议抽象成明确用途、带类型、且默认不执行的函数：
立即学习“Java免费学习笔记（深入）”；
- 创建
lib/server-utils.ts，导出函数而非立即执行：
export async function readConfigFile() {<br> if (typeof window !== 'undefined') throw new Error('Not available on client');<br> const fs = await import('fs').then(m => m.default || m);<br> return fs.promises.readFile('./config.json', 'utf8');<br>} - 这样既保证客户端代码中引用该模块不会触发 fs 加载（除非调用函数），也利于 TypeScript 类型推导和测试模拟
- 避免在模块顶层写
const fs = require('fs');—— 这会导致服务端模块被静态依赖链捕获
利用框架的 server-only 标识机制
现代轻量 SSR 框架普遍支持“仅服务端”模块语义：
- SvelteKit：文件名后缀
.server.ts（或.server.js），框架自动禁止其被客户端导入 - Astro：组件内
---<br>import { something } from './utils.server.js';<br>---，Astro 编译器会剥离该行并仅在服务端执行 - Remix：
loader和action函数天然运行于服务端，其中的require安全 - 关键：这类机制本质是构建时静态分析 + 文件路径约定，比运行时判断更可靠，优先采用
不复杂但容易忽略——CommonJS 本身不是问题，问题在于模块边界是否清晰。把服务端依赖关进“运行时才打开的盒子”，再用打包配置和框架约定加固这道门，就能稳住 SSR 的轻量与可靠。
