Laravel 11集成Lightbox2报错：Cannot read properties of undefined (reading 'jQuery')

我正在Laravel项目中集成Lightbox2画廊脚本，打包工具已完成文件打包，但脚本无法执行，控制台报错：

Uncaught TypeError: Cannot read properties of undefined (reading 'jQuery')

报错位置在lightbox-plus-jquery.js的第11021行。

环境配置 #

• 框架：Laravel 11 + Breeze（Blade模板）
• 打包工具：Vite 5

我尝试在页面中添加Lightbox2画廊，使用npm包遇到问题后，直接从仓库下载压缩包，手动将以下文件放入resources目录：

• dist/css/lightbox.css
• dist/js/lightbox-plus-jquery.js（因Laravel默认不包含jQuery）

lightbox.css已在resources/js/app.js中导入，lightbox-plus-jquery.js在vite.config.js中的配置如下：

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/tinymce/tinymce.min.js',
                'resources/js/app.js',
                'resources/js/lightbox/lightbox-plus-jquery.js',
            ],
            refresh: true,
        }),
    ],
});

Vite脚本通过@vite方法在Blade文件中导入：

@vite([
    'resources/css/style.css', 
    'resources/js/app.js',
    'resources/js/lightbox/lightbox-plus-jquery.js',
])

Blade视图通过循环图片数组生成Lightbox文档推荐的结构：

<div class="gallery" >
    @if($project->gallery)
        @foreach($project->gallery as $image)
            <a href="{{ asset($image) }}" data-lightbox="gallery-item" >
                <img src="{{ asset($image) }}" alt="{{$title . ' : ' . $image}}" />
            </a>
        @endforeach 
    @endif
</div>

核心原因 #

lightbox-plus-jquery.js虽内置jQuery，但Vite的模块打包机制会将jQuery封装在局部作用域内，无法暴露到全局环境，导致Lightbox找不到全局的jQuery变量。

方案1：手动暴露全局jQuery #

1. 先安装jQuery（未安装的话）：

npm install jquery

2. 修改resources/js/app.js，导入并暴露jQuery到全局，再引入Lightbox脚本：

import $ from 'jquery';
window.jQuery = window.$ = $;

// 导入Lightbox脚本
import '../js/lightbox/lightbox-plus-jquery.js';

3. 修改vite.config.js，移除input中的lightbox-plus-jquery.js（已在app.js中导入）：

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/tinymce/tinymce.min.js',
                'resources/js/app.js',
            ],
            refresh: true,
        }),
    ],
});

4. 简化Blade中的@vite引用：

@vite([
    'resources/css/style.css', 
    'resources/js/app.js',
])

方案2：使用纯Lightbox版本 + 全局jQuery #

1. 下载不带jQuery的lightbox.js，放入resources/js/lightbox/目录
2. 在app.js中导入全局jQuery和纯Lightbox脚本：

import $ from 'jquery';
window.jQuery = window.$ = $;
import '../js/lightbox/lightbox.js';

3. 后续配置同方案1，移除Vite和Blade中对Lightbox脚本的单独引用。

方案3：通过Vite配置全局注入jQuery #

1. 安装依赖：

npm install @rollup/plugin-inject --save-dev

2. 修改vite.config.js，添加全局注入配置：

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import inject from '@rollup/plugin-inject';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/tinymce/tinymce.min.js',
                'resources/js/app.js',
                'resources/js/lightbox/lightbox-plus-jquery.js',
            ],
            refresh: true,
        }),
        inject({
            $: 'jquery',
            jQuery: 'jquery',
        }),
    ],
});

内容的提问来源于stack exchange，提问作者Basile