动态导入在SSR中易出错，核心是服务端不支持浏览器API、模块未标记可服务端执行、水合不一致；应精准控制执行时机与环境，禁用不兼容模块，用next/dynamic(ssr:false)，确保DOM结构一致，避免hydration失败。
动态导入（import()）在 SSR 环境中容易出错，核心问题在于：服务端不支持浏览器 API、模块未正确标记可服务端执行、水合不一致。处理的关键不是“禁用”，而是“精准控制执行时机和环境”。
明确哪些模块必须禁用 SSR
第三方 UI 库（如 react-chartjs-2、mapbox-gl）、依赖 window/document 的工具类、含 DOM 操作的组件，都不该在服务端运行。
- 使用
next/dynamic并设置ssr: false，强制只在客户端加载 - 避免在
getServerSideProps或服务端组件中调用import() - 不要把动态导入写在顶层或服务端逻辑分支里，比如
if (typeof window !== 'undefined') import(...)是无效的——服务端解析阶段就会报错
需要 SSR 的模块要确保环境兼容
如果某个包本身支持 SSR（如 date-fns、lodash），但你仍用 import() 加载，需确认它没有副作用、不访问浏览器对象。
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 优先使用静态导入（
import { format } from 'date-fns'），更稳定且利于服务端打包分析 - 若必须动态加载（例如按语言拆分 i18n 包），确保导出的是纯函数或 JSON 数据，不含
new Worker()、localStorage等客户端专属逻辑 - 在 Webpack 或 Turbopack 配置中检查
externals和target，避免把 Node.js 内置模块误打包进客户端
规避水合不一致的陷阱
服务端渲染时跳过某块内容，客户端却渲染出来，会导致 React/Vue 报 “Hydration failed” 警告甚至白屏。
- 动态组件必须配合 loading 状态和占位结构，让服务端与客户端 DOM 结构一致
- 示例中
<ClientOnlyComponent />在服务端应渲染为<div></div>或<p>Loading</p>，不能是空字符串或null - 避免在服务端返回
<div>Hello</div>，客户端却渲染成<section>Hello</section>—— 标签类型、class、key 都要严格对齐
调试与验证方法
光看控制台错误不够，要从请求源头确认行为是否符合预期。
- 查看 Network 面板中 HTML 响应体：动态组件区域是否为空或含 loading 占位符
- 在服务端加
console.log('SSR running')，在useEffect里加console.log('Client mounted')，对比执行顺序 - 用
curl http://localhost:3000直接抓取原始 HTML，确认关键内容是否存在，而非依赖浏览器 DevTools 的 Elements 面板（它显示的是 hydration 后状态）
