lightbox.js（常见实现 Lightbox2）解决的是“点缩略图弹出大图、可左右翻页”这一交互。它靠 data-lightbox 属性自动绑定，几乎不用写 JS，但也因此遇到“点了没反应”“图片路径 404”“和 jQuery 版本冲突”等典型问题。本文按官方文档走一遍用法与排错。

一、安装与文件要求

官方项目页 https://lokeshdhakar.com/projects/lightbox2/ 给出两种安装方式：

npm install lightbox2 --save

或直接下载 GitHub Releases 的 zip，里面 /examples 是可运行的最简样例。MIT 协议，商用免费，但要求保留作者名、主页链接与许可证信息（这些可以只留在代码注释里，不必显示在页面上）。

引入顺序有讲究：CSS 放 <head>，JS 放 </body> 前，并且必须在此之前先加载 jQuery。Lightbox2 依赖 jQuery 1.7 以上，且因为用到了 effects 模块，不支持 jQuery slim 版本（slim 去掉了动画，这会直接导致弹出动画报错）。如果项目本来没有 jQuery，官方提供打包版：

<link rel="stylesheet" href="dist/css/lightbox.min.css">
<!-- 二选一：项目已有 jQuery 就用 lightbox.min.js，没有就用带 jQuery 的合集 -->
<script src="dist/js/lightbox-plus-jquery.min.js"></script>

还有一个非常容易被漏的点：`lightbox.css` 会引用 /dist/images/ 下的四张图（close.png、loading.gif、next.png、prev.png）。目录没一起上传时，关闭按钮和左右箭头全是空白，看起来“功能坏了”，其实是图片 404，看 Network 面板即可确认。

二、用 HTML 属性启用

单图：给链接加 data-lightbox，值是唯一标识：

<a href="images/big1.jpg" data-lightbox="album-1" data-title="第一张的说明">
  <img src="images/thumb1.jpg" alt="第一张">
</a>

图集：多张图片使用相同的 data-lightbox 值，即可自动成组、出现左右箭头与“Image 2 of 4”计数：

<a href="images/big2.jpg" data-lightbox="product"><img src="t2.jpg" alt=""></a>
<a href="images/big3.jpg" data-lightbox="product"><img src="t3.jpg" alt=""></a>
<a href="images/big4.jpg" data-lightbox="product"><img src="t4.jpg" alt=""></a>

可选属性：data-title 显示说明文字，data-alt 设置放大图的 alt（无障碍与 SEO 都有用）。注意 href 必须指向原图，img src 指向缩略图，两者搞反就会看到小图放大后的马赛克效果。

三、常用配置项

通过 lightbox.option({...}) 修改默认值（官方文档列出的主要项）：

• albumLabel: "图片 %1 / %2" —— 本地化计数文案，中文站必改；
• wrapAround: true —— 到最后一张时可继续前进回到第一张；
• fitImagesInViewport: true（默认开）—— 超尺寸图片自动缩到视口内；
• maxWidth / maxHeight —— 限制显示尺寸（设了之后不再保持宽高比，慎用）；
• fadeDuration: 600、imageFadeDuration: 600、resizeDuration: 700 —— 三段动画时长（毫秒）；
• positionFromTop: 50 —— 距视口顶部距离；
• disableScrolling: true —— 打开时禁止背景滚动（实现方式是给 body 设 overflow hidden）；
• showImageNumberLabel: false —— 隐藏计数；alwaysShowNavOnTouchDevices: true —— 触屏设备常驻左右箭头。

lightbox.option({
  albumLabel: "第 %1 张，共 %2 张",
  wrapAround: true,
  fadeDuration: 300,
  resizeDuration: 300,
  disableScrolling: true
});

四、编程式 API

官方提供的可调用方法：open(images, startIndex)、close()、next()、prev()、destroy()。open 可以传单张 URL 字符串，也可以传 {link, title, alt} 对象数组：

lightbox.open([
  { link: 'a.jpg', title: 'A', alt: 'A 图' },
  { link: 'b.jpg', title: 'B', alt: 'B 图' }
], 0);

单页应用（Vue/React 动态插入内容）里务必注意：destroy() 会移除 DOM 并解绑所有事件，用来做组件卸载清理；反过来，如果内容是后来异步加载进来的，Lightbox 的事件绑定基于 document 委托，仍能生效，但如果调过 destroy() 就需要重新初始化。

五、样式定制与无障碍

新版支持用 CSS 自定义属性覆盖外观，不必改源码 CSS；同时内置无障碍：容器带 role="dialog" 与 aria-modal，打开时焦点被限制在灯箱内、关闭后焦点回到触发元素。自己做替换方案时这两点必须补齐。

六、常见问题 FAQ

问：点击缩略图直接打开图片文件，灯箱没出现？
答：依次查——(1) 是否加载了 jQuery 且在 lightbox.js 之前；(2) 用的是不是 jQuery slim；(3) 属性名是不是写成了 data-lightboxy 或大小写错误；(4) JS 是否报错（Console 红色信息）。

问：弹出层位置偏下、被固定导航遮挡？
答：Lightbox 用绝对定位，页面有 position:fixed 头部时容易错位。可改 positionFromTop，或升级新版（新版对定位做了改进）。

问：手机上门户浏览器点大图没反应？
答：多为图片过大导致加载超时，用“缩略图 + 中等尺寸 + 原图”三档，或直接换零依赖方案（官方也提到 Lightbox 3 为无依赖版本）。

问：能不能不用 jQuery？
答：可以。原生方案是自己写一个 <dialog> + preload 的灯箱，或用 <div class="lightbox"> 手写 30 行代码；也可以选用无依赖的图库（PhotoSwipe、Fancybox 的新版）。

一句话：Lightbox2 的价值是“零 JS、加个属性就能用”，代价是必须引 jQuery 且要带对四张图标。理解这两点，排错就很快。

• javascript
• 前端开发
• 图片组件