Next.js中不能直接import Bootstrap CSS，因SSR环境无window/DOM导致ReferenceError及hydration mismatch；正确做法是在layout.tsx或_app.tsx中全局导入CSS，JS组件须用'use client'配合useEffect动态加载。
Bootstrap 5 不能直接和 Next.js 的 SSR/SSG 流程兼容，强行用 import 'bootstrap/dist/css/bootstrap.min.css' 会导致服务端渲染时样式丢失、客户端水合错乱，甚至触发 React hydration mismatch 错误。
为什么 import 'bootstrap/dist/css/bootstrap.min.css' 在 pages/ 或 app/ 中会出问题
Next.js 默认在服务端执行组件逻辑，但 Bootstrap 的 CSS 文件依赖 window 和 DOM API（比如 Tooltip、Dropdown 初始化），而服务端没有这些。更关键的是：CSS 文件 import 是全局副作用操作，在服务端执行会污染模块缓存，且无法被 Next.js 的 CSS 预处理链识别 —— 导致样式不生效、useEffect 中手动初始化失败、next export 静态导出时报错。
- 常见错误现象：
ReferenceError: window is not defined、Hydration failed because the initial UI does not match what was rendered on the server - 使用场景：仅适用于纯客户端渲染（CSR）页面，比如用
useClient包裹的组件，或放在useEffect内动态加载 - 性能影响：全局 CSS import 会阻塞首屏 JS 解析，且无法按需提取，增大 TTFB 和 FCP
正确安装 Bootstrap 5 + React 组件（推荐 react-bootstrap）
用封装好的 React 组件替代原生 Bootstrap JS 行为，彻底规避 DOM 依赖。官方推荐方案是 react-bootstrap，它不依赖 jQuery，也不调用 window，纯函数式组件，天然适配 SSR。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 安装命令：
npm install react-bootstrap bootstrap - 只在
app/layout.tsx（App Router）或pages/_app.tsx（Pages Router）中 import CSS：import 'bootstrap/dist/css/bootstrap.min.css'—— 这里是安全的，因为 Next.js 会自动将其提升为全局样式入口 - 组件全部从
react-bootstrap导入，例如：import { Button, Modal } from 'react-bootstrap'，不要用原生<button class="btn btn-primary"> - 禁用 Bootstrap 自带 JS 行为（如 Collapse、Dropdown）：它们在 SSR 下仍可能出问题；优先用
react-bootstrap提供的受控组件（show/onHide等 props）
如果必须用原生 Bootstrap JS（如 Popover、Toast），怎么绕过 SSR
只能把依赖 DOM 的行为推迟到客户端。Next.js 不允许在服务端运行 new bootstrap.Popover() 这类代码，必须包裹在 useEffect 或动态 import() 中。
- 动态导入 JS（推荐）：
const bootstrap = await import('bootstrap')放在useEffect内，确保只在浏览器执行 - 用
dynamic(..., { ssr: false })包裹整个使用 Bootstrap JS 的组件，例如：dynamic(() => import('../components/BootstrapTooltip'), { ssr: false }) - 别在
getServerSideProps或getStaticProps里调用bootstrap.Toast—— 这些函数运行在 Node 环境，bootstrap会直接报错 - 注意：动态导入后，CSS 仍需提前引入（见上一节），否则样式缺失
React-Bootstrap vs 原生 Bootstrap + 自己写组件：选哪个
除非你有强定制需求（比如要复用大量已有的 Bootstrap SASS 变量、深度改写 _dropdown.scss），否则 react-bootstrap 是更省心的选择。它的组件 API 更 React 化，支持 TypeScript 类型推导，且社区维护活跃（v2.9+ 已完全适配 Bootstrap 5.3）。
- 优点：
react-bootstrap组件默认支持 SSR、可服务端预渲染、无 runtime DOM 依赖、支持服务端生成静态 HTML - 缺点：部分高级交互（如 Offcanvas 多层嵌套）API 抽象略重；若项目已有大量 jQuery Bootstrap 插件，迁移成本高
- 容易被忽略的点：不要混用
react-bootstrap和原生data-bs-*属性 —— 比如同时写<Button variant="primary">和data-bs-toggle="modal"，会导致行为冲突
