必须删除bootstrap栅格类，否则masonry会因flex/float与js“砌砖”逻辑冲突而重叠错位；需用语义化容器、纯子项标签、css控宽、imagesloaded前置校验图片加载，并监听resize重排布局。

Bootstrap 栅格类必须全删，否则 Masonry 会重叠错位

直接在 .row 里套 .col-md-4，再初始化 Masonry，99% 会出问题。因为 Bootstrap 的栅格靠 flex 或 float 做行内布局，而 Masonry 是 JS 拿所有子项重新按列“砌砖”——两者逻辑冲突，CSS 宽度、 margin、flex-basis 全都会干扰 Masonry 的位置计算。

实操建议：

VPS Bootstrap

从零启动全新 VPS，完成 OpenClaw 完整部署，包括备份/恢复及恢复后验证。用于 OpenClaw 部署。

下载

• 容器只保留语义化结构，比如 <div class="masonry">，不要加 <code>row
• 子项用纯标签（如 <article></article> 或 <div class="item">），移除所有 <code>col-* 类
• 宽度改由 CSS 控制，例如：width: calc(33.333% - 1rem);（对应三列 + 间隙）
• 若需响应式列数变化，不能只改 CSS，必须调用 masonry.layout()

imagesLoaded 不是可选插件，是 Masonry 正常工作的前提

没等图片加载完就执行 masonry()，JS 读到的子项高度全是 0 或默认值，结果就是卡片堆叠、错位、漏排——这不是 bug，是必然行为。

常见错误现象：Uncaught TypeError: Cannot read property 'offsetTop' of undefined 或视觉上大量重叠。

实操建议：

• 引入顺序必须是：jQuery → imagesLoaded → Masonry
• 初始化必须包裹在 imagesLoaded 回调里：$('.masonry').imagesLoaded(() => { $('.masonry').masonry({ itemSelector: '.item' }); });
• 如果子项含 <picture></picture> 或懒加载 data-src，得手动触发 imagesLoaded 或用 background-image 的伪元素 hack

移动端 Safari 的 column-count 兼容性坑比想象中深

虽然 column-count 看似轻量，但 iOS Safari（尤其旧版）对 break-inside: avoid 支持不稳定，经常导致卡片被截断、图片溢出、列间间距错乱。2026 年最新测试显示：Safari 17+ 表现尚可，但 iOS 15 及更早版本仍存在渲染抖动。

实操建议：

• 若必须用 CSS 方案，给子项加 break-inside: avoid-column;（比 avoid 更稳妥）
• 图片强制加 max-width: 100%; height: auto;，避免撑破列宽
• 用 @supports (column-count: 3) 包裹样式，并 fallback 到单列或 flex wrap
• 真要保兼容又不想写 JS？直接放弃 column-count，Masonry + imagesLoaded 是当前最稳路径

响应式列数切换时，Masonry 不会自动重排

很多人以为改了 @media 里的 width 或加个 col-6 类就能响应式，但 Masonry 初始化后不会监听窗口 resize 或类名变更——它只认初始 DOM 和尺寸快照。

实操建议：

• 监听 resize 事件，节流后调用 masonry.layout()
• 如果用 Bootstrap 断点切换列数（比如从 3 列变 1 列），应在 JS 中同步更新 columnWidth 配置并重排
• 避免在 itemSelector 里用动态类名（如 .col-sm-6），会导致 Masonry 找不到目标项

真正难的不是引入 Masonry，而是让它的计算和页面生命周期对齐——图片加载时机、DOM 就绪状态、CSS 宽度生效顺序，三者稍有错位，瀑布流就塌一半。