Lychee项目子目录部署时的图标加载问题分析与解决方案

问题背景

Lychee是一个开源的图片管理系统，最新发布的6.0.0版本在部署到子目录时出现了一个界面图标无法显示的问题。这个问题影响了使用子目录部署(如domain.tld/lychee)的所有用户，导致界面上的图标全部消失，严重影响了用户体验。

问题现象

当Lychee被安装在子目录下运行时，用户界面中的图标无法正常显示。通过浏览器开发者工具检查，可以看到以下错误信息：

downloadable font: no supported format found (font-family: "primeicons" style:normal weight:400 stretch:100 src index:5)

具体表现为三种字体文件加载失败：

• primeicons.woff2
• primeicons.woff
• primeicons.ttf

技术分析

根本原因

经过技术分析，问题的根源在于Vite构建工具的配置问题。在构建前端资源时，Vite错误地使用了绝对路径(/)作为基础路径，而不是相对路径(./)。这导致在子目录部署时，浏览器会尝试从网站根目录而不是子目录下加载字体资源。

具体表现

正常情况下，当Lychee部署在子目录(如/Lychee)时，字体资源应该从以下路径加载：

https://example.com/Lychee/build/assets/primeicons-C6QP2o4f.woff2

但由于配置错误，浏览器实际尝试从以下路径加载：

https://example.com/build/assets/primeicons-C6QP2o4f.woff2

缺少了子目录前缀，导致资源加载失败。

解决方案

Lychee开发团队已经识别了这个问题并提交了修复。解决方案是修改Vite的构建配置，将基础路径从绝对路径(/)改为相对路径(./)，确保资源引用能正确适应子目录部署场景。

临时解决方法

对于急需解决问题的用户，可以尝试以下临时解决方案：

1. 修改Nginx/Apache配置，添加重写规则将字体请求重定向到正确的子目录路径
2. 手动将字体文件复制到网站根目录下的build/assets目录中
3. 等待官方发布包含此修复的更新版本

预防措施

为了避免类似问题，开发者在进行子目录部署测试时应该：

1. 全面测试所有静态资源的加载情况
2. 检查构建工具的路径配置
3. 确保.env文件中的APP_DIR和APP_URL设置正确
4. 在不同部署场景下进行充分测试

总结

Lychee 6.0.0版本在子目录部署时出现的图标加载问题，主要是由于前端构建工具的路径配置不当导致的。开发团队已经识别并修复了这个问题，用户可以通过等待更新或采用临时解决方案来处理。这个案例也提醒我们，在软件开发中，路径处理是一个需要特别注意的细节，特别是在支持多种部署场景时。