Laravel项目构建Swagger时遇Vite编译错误及页面加载异常

CSS压缩语法警告处理 #

问题原因 #

Swagger UI自带的CSS里包含了IE兼容的*zoom:1私有语法，而Vite默认使用的esbuild压缩器不支持这种非标准CSS写法，导致构建阶段抛出Expected identifier but found "*"警告。

解决步骤 #

• 切换CSS压缩器为LightningCSS：在vite.config.js中修改配置，用LightningCSS替代esbuild处理CSS压缩，它对旧语法兼容性更好：

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

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

• 若不需要IE兼容，也可以直接定位到Swagger CSS文件中的.swagger-ui .cf{*zoom:1}行，删除该私有样式（不推荐，可能影响旧浏览器兼容）。

JS加载异常处理 #

问题原因 #

构建时的tree shaking或代码压缩逻辑误剔除了Swagger UI运行所需的核心模块，导致页面加载时出现Cannot read properties of undefined (reading 'isRequired')的TypeError。

解决步骤 #

1. 配置Vite优化依赖：在vite.config.js中添加Swagger相关包到优化列表，避免被tree shaking移除：

export default defineConfig({
    // ...其他配置
    optimizeDeps: {
        include: ['swagger-ui', 'swagger-ui-dist'],
    },
});

2. 检查Swagger版本兼容性：确保安装的swagger-ui或swagger-ui-dist版本与当前Laravel/Vite版本兼容，尝试升级或降级版本，比如执行：

npm uninstall swagger-ui
npm install swagger-ui@latest

3. 完整导入Swagger资源：在resources/js/app.js中确保完整导入Swagger的脚本和样式，避免按需导入导致的模块缺失：

import 'swagger-ui-dist/swagger-ui.css';
import SwaggerUI from 'swagger-ui';

// 初始化Swagger UI
SwaggerUI({
    url: '/api/documentation',
    dom_id: '#swagger-ui',
});

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