故障排查

本文档帮助你诊断和解决使用千字网CDN时可能遇到的技术问题。

字体加载问题

问题：字体无法加载

症状：

页面显示默认字体
浏览器控制台显示404错误
Network 标签中字体文件加载失败

排查步骤：

检查URL是否正确

css

/* 确认字体文件夹名拼写正确 */
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

验证字体文件可访问
- 直接在浏览器中访问字体URL
- 确认返回CSS内容而非404错误
检查网络连接
- 确认能访问CDN域名
- 尝试其他域名（如 hanzi.bluu.pl）
查看浏览器控制台
- 打开开发者工具（F12）
- 检查 Console 和 Network 标签
- 查找错误信息

解决方案：

修正URL拼写错误
切换到其他CDN域名
检查网络连接

问题：字体加载超时

症状：

字体加载时间过长
页面长时间显示空白

排查步骤：

检查网络速度
- 使用网速测试工具检查连接速度
- 确认网络稳定
检查字体文件大小
- 查看字体文件是否异常大
- 正常字体文件应在100KB-500KB之间
使用浏览器缓存
- 清除浏览器缓存
- 使用隐私模式测试

解决方案：

使用加速域名 https://hanzi.itedev.com
设置 font-display: swap 提升体验
考虑预加载字体文件

问题：CORS 错误

症状：

浏览器控制台显示 CORS 错误
字体文件被浏览器阻止加载

排查步骤：

检查CDN域名配置
- 确认CDN正确设置CORS头
- 查看响应头是否包含 Access-Control-Allow-Origin
检查HTTPS/HTTP
- 确认协议匹配
- 混合协议可能导致CORS问题

解决方案：

使用正确的协议（HTTPS或HTTP）
联系CDN提供商检查CORS配置

显示问题

问题：字体显示不正确

症状：

字体族名设置后仍显示默认字体
部分字符显示为方框或问号

排查步骤：

检查font-family名称

css

/* 确认字体族名正确，注意空格和引号 */
body {
    font-family: 'Source Han Sans VF', sans-serif;
}

检查字符支持
- 确认字体包含所需字符
- 查看字体字符集说明

检查字体加载顺序

css

/* 确认字体在回退列表中位置正确 */
body {
    font-family: 'Source Han Sans VF', 'PingFang SC', sans-serif;
}

解决方案：

修正 font-family 名称
使用包含所需字符的字体
调整字体回退顺序

问题：字体模糊或锯齿

症状：

字体显示模糊
边缘有锯齿感

排查步骤：

检查字体格式
- 确认使用WOFF2格式
- WOFF2提供更好的渲染质量
检查浏览器设置
- 查看浏览器字体渲染设置
- 尝试调整字体平滑选项
检查屏幕分辨率
- 高分辨率屏幕可能需要调整
- 使用媒体查询优化

解决方案：

使用WOFF2格式字体
调整浏览器字体渲染设置
针对高分辨率屏幕优化

性能问题

问题：页面加载缓慢

症状：

页面加载时间长
字体文件加载时间过长

排查步骤：

检查引用的字体数量

css

/* 避免引用过多字体 */
@import url("https://hanzi.itedev.com/fonts/字体1/result.css");
@import url("https://hanzi.itedev.com/fonts/字体2/result.css");
@import url("https://hanzi.itedev.com/fonts/字体3/result.css");

检查字体文件大小
- 查看Network标签中字体文件大小
- 确认字体已进行拆包优化
检查网络连接
- 测试网络速度
- 确认CDN节点响应正常

解决方案：

只引用必要的字体
使用加速域名
设置 font-display: swap
考虑预加载关键字体

问题：字体闪烁

症状：

页面加载时字体闪烁
字体切换时出现跳动

排查步骤：

检查font-display设置

css

/* 确认使用了合适的font-display值 */
@font-face {
    font-family: 'Source Han Sans VF';
    font-display: swap; /* 或其他合适值 */
}

检查字体加载顺序
- 确认字体CSS优先加载
- 避免字体加载延迟

解决方案：

使用 font-display: swap
预加载字体文件
优化字体加载顺序

兼容性问题

问题：IE浏览器不显示字体

症状：

IE浏览器显示默认字体
字体无法加载

排查步骤：

检查浏览器版本
- 确认IE版本
- 千字网CDN不支持IE浏览器
检查字体格式
- WOFF2格式不被IE支持
- 需要使用WOFF或EOT格式

解决方案：

升级到现代浏览器
使用支持IE的字体CDN服务

问题：移动端显示异常

症状：

移动设备字体显示不正确
字体大小或样式异常

排查步骤：

检查媒体查询

css

/* 确认移动端样式正确 */
@media (max-width: 768px) {
    body {
        font-size: 16px;
    }
}

检查viewport设置

html

<meta name="viewport" content="width=device-width, initial-scale=1.0">

解决方案：

优化移动端样式
设置正确的viewport
测试不同移动设备

网络问题

问题：无法访问CDN域名

症状：

无法访问 hanzi.itedev.com
无法访问 hanzi.bluu.pl
DNS解析失败

排查步骤：

检查DNS解析

bash

# Windows
nslookup hanzi.itedev.com

# Mac/Linux
dig hanzi.itedev.com

检查网络连接
- 确认网络连接正常
- 尝试访问其他网站
检查防火墙设置
- 确认防火墙未阻止CDN域名
- 检查代理设置

解决方案：

切换DNS服务器
检查防火墙设置
尝试其他CDN域名

问题：间歇性连接失败

症状：

字体有时加载成功，有时失败
连接不稳定

排查步骤：

检查网络稳定性
- 测试网络连接稳定性
- 查看丢包率
检查CDN节点状态
- 确认CDN节点运行正常
- 查看CDN状态页面

解决方案：

使用更稳定的网络连接
切换到其他CDN域名
设置字体回退方案

诊断工具

浏览器开发者工具

使用方法：

按F12打开开发者工具
选择 "Network" 标签
刷新页面
查看字体文件加载情况

关键信息：

文件大小
加载时间
状态码（200、404等）
响应头

在线字体检测工具

推荐工具：

获取帮助

如果以上方法无法解决你的问题：

查看其他文档
联系支持
- 邮箱：[email protected]
- 提供详细的错误信息和环境信息
报告问题
- 描述问题症状
- 提供复现步骤
- 附上错误截图

故障排查 ​

字体加载问题 ​

问题：字体无法加载 ​

问题：字体加载超时 ​

问题：CORS 错误 ​

显示问题 ​

问题：字体显示不正确 ​

问题：字体模糊或锯齿 ​

性能问题 ​

问题：页面加载缓慢 ​

问题：字体闪烁 ​

兼容性问题 ​

问题：IE浏览器不显示字体 ​

问题：移动端显示异常 ​

网络问题 ​

问题：无法访问CDN域名 ​

问题：间歇性连接失败 ​

诊断工具 ​

浏览器开发者工具 ​

在线字体检测工具 ​

获取帮助 ​

故障排查

字体加载问题

问题：字体无法加载

问题：字体加载超时

问题：CORS 错误

显示问题

问题：字体显示不正确

问题：字体模糊或锯齿

性能问题

问题：页面加载缓慢

问题：字体闪烁

兼容性问题

问题：IE浏览器不显示字体

问题：移动端显示异常

网络问题

问题：无法访问CDN域名

问题：间歇性连接失败

诊断工具

浏览器开发者工具

在线字体检测工具

获取帮助