Webpack Encore集成UniversalViewer V4时CSS无法构建的问题

问题描述 #

在Symfony应用中集成UniversalViewer V4，通过yarn add universalviewer安装后，执行yarn encore dev时JS功能正常，但CSS未被构建。尝试在app.css中添加@import "/universalviewer";后，编译出现以下错误：

ERROR  Failed to compile with 2 errors

 error  in ./node_modules/universalviewer/dist/cjs/index.js

Syntax Error: CssSyntaxError

(1:1) /var/www/myproject/node_modules/universalviewer/dist/cjs/index.js Unknown word

当前webpack.config.js配置如下：

const Encore = require('@symfony/webpack-encore');

if (!Encore.isRuntimeEnvironmentConfigured()) {
    Encore.configureRuntimeEnvironment(process.env.NODE_ENV || 'dev');
}

Encore
    .setOutputPath('public/build/')
    .setPublicPath('/build')
    .addEntry('app', './assets/app.js')
    .enableStimulusBridge('./assets/controllers.json')
    .splitEntryChunks()
    .enableSingleRuntimeChunk()
    .cleanupOutputBeforeBuild()
    .enableBuildNotifications()
    .enableSourceMaps(!Encore.isProduction())
    .enableVersioning(Encore.isProduction())
;

module.exports = Encore.getWebpackConfig();

错误原因 #

• 直接在CSS中导入/universalviewer会让CSS loader尝试解析UniversalViewer的JS入口文件（index.js），而CSS loader无法识别JS语法，导致报错。
• UniversalViewer的CSS是单独打包在dist/uv.css文件中的，并非通过JS模块导出，需要指定正确的CSS文件路径导入。

解决步骤 #

1. 正确引入UniversalViewer的CSS #

修改assets/app.css，导入UniversalViewer的专用CSS文件，使用~让Webpack从node_modules目录查找：

/* assets/app.css */
@import "~universalviewer/dist/uv.css";

2. 确保Webpack Encore支持CSS处理 #

检查Encore配置，确保已启用CSS相关加载器。如果项目未配置，在webpack.config.js中添加以下配置：

Encore
    // ... 保留原有配置 ...
    .enablePostCssLoader() // 启用PostCSS（可选，根据项目需求）
    .configureCssLoader(options => {
        options.modules = false; // 禁用CSS模块化，确保全局CSS生效
    })
;

Symfony Encore通常默认已配置基础CSS处理，若已有相关配置可跳过此步骤。

3. 重新执行构建 #

运行构建命令重新编译：

yarn encore dev

此时UniversalViewer的CSS会被正确打包到输出的app.css文件中。

4. 验证JS引入 #

在assets/app.js中正确导入并初始化UniversalViewer：

// assets/app.js
import UniversalViewer from 'universalviewer';

// 初始化示例（需确保页面存在id为uv的元素）
const uv = new UniversalViewer({
    element: document.getElementById('uv'),
    manifest: '你的资源清单URL'
});

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