CoreUI Bootstrap Laravel部署服务器后自定义外部字体不生效问题

架构老林

2026-9-2

问题原因

本地正常线上字体回退到默认字体，本质是浏览器加载Vazir字体失败，常见诱因有以下几类：

路径匹配错误：你当前写的相对路径../../fonts/Vazir.ttf是基于sass源文件位置的相对路径，线上部署如果项目目录层级、站点根目录配置和本地不一致，或者Laravel Mix未正确处理资源路径，编译后CSS里的字体路径和服务器实际存放路径不匹配，请求字体返回404。
服务器配置缺失：Nginx/Apache默认未配置.ttf等字体格式的MIME类型，导致字体请求被拦截，返回不符合预期的响应类型，浏览器无法识别为字体文件。
权限不足：服务器上fonts目录或Vazir.ttf文件权限配置错误，Web服务进程无读取权限，请求返回403。
资源未正确编译/上传：部署时只上传了sass源文件，未执行生产环境编译命令，线上加载的仍是旧版本CSS文件；或者编译后未将字体文件、编译后的CSS文件全量上传到服务器对应目录。
跨域拦截：如果静态资源托管在独立CDN/子域名下，字体请求触发浏览器CORS跨域限制，被拦截无法加载。
缓存影响：浏览器或CDN缓存了旧版本的CSS资源，未加载到包含自定义字体规则的新CSS文件。

排查与解决步骤

先定位具体错误：打开浏览器开发者工具（F12），切换到「Network」面板，筛选Font类型请求，刷新页面找到Vazir.ttf的请求记录，根据状态码对应处理：
- 状态码为404：修正字体引用路径。不要在sass里写多层相对路径，将字体文件放到resources/fonts目录下，把@font-face的src改为src: url('~/fonts/Vazir.ttf')，Laravel Mix编译时会自动解析为正确的公开访问路径；如果项目部署在站点子目录下，需要在webpack.mix.js中添加mix.setResourceRoot('/你的项目子目录路径/')，之后重新执行编译命令。
- 状态码为403：先调整文件权限，将服务器上public/fonts目录权限设为755，目录内字体文件权限设为644，保证Web运行用户（如www-data、nginx）有读取权限；如果权限调整后仍报403，按下面的步骤配置服务器MIME类型。

配置服务器字体支持：

Nginx环境在站点配置中添加以下规则，配置完成后执行nginx -s reload重载配置：

location ~* \.(ttf|ttc|otf|eot|woff|woff2|svg)$ {
    add_header Access-Control-Allow-Origin *;
    types {
        font/ttf ttf;
        font/woff woff;
        font/woff2 woff2;
        application/vnd.ms-fontobject eot;
        font/otf otf;
        image/svg+xml svg;
    }
}

Apache环境在项目public/.htaccess文件中添加以下规则：

AddType font/ttf .ttf
AddType font/woff .woff
AddType font/woff2 .woff2
AddType application/vnd.ms-fontobject .eot
AddType font/otf .otf
<FilesMatch "\.(ttf|ttc|otf|eot|woff|woff2|svg)$">
    Header set Access-Control-Allow-Origin "*"
</FilesMatch>

正确编译上传资源：本地修改完配置后执行npm run production生成生产环境压缩后的CSS、JS资源，将public目录下编译生成的css、js、fonts目录全量上传到服务器对应位置，不要只上传sass源文件。上传后可以打开编译后的public/css/app.css文件，搜索vazir关键字，确认自定义字体规则已经被正确编译到文件中，同时检查app.scss入口文件是否已经通过@import 'custom'引入了你修改的_custom.sass文件，避免sass文件未参与编译。
跨域场景处理：如果静态资源使用CDN托管，需要在CDN后台配置CORS规则，允许你的业务域名跨域访问字体资源；无特殊需求的话可以直接将字体文件存放到业务域名同域下的public/fonts目录，规避跨域问题。
清理缓存：部署完成后清空浏览器缓存、CDN缓存，避免加载旧版本资源。

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