故障排查

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

目录

字体加载问题

问题：字体无法加载

症状：

排查步骤：

  1. 检查URL是否正确

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

  2. 验证字体文件可访问

    • 直接在浏览器中访问字体URL
    • 确认返回CSS内容而非404错误

  3. 检查网络连接

    • 确认能访问CDN域名
    • 尝试其他域名（如 hanzi.bluu.pl）

  4. 查看浏览器控制台

    • 打开开发者工具（F12）
    • 检查 Console 和 Network 标签
    • 查找错误信息

解决方案：

问题：字体加载超时

症状：

排查步骤：

  1. 检查网络速度

    • 使用网速测试工具检查连接速度
    • 确认网络稳定

  2. 检查字体文件大小

    • 查看字体文件是否异常大
    • 正常字体文件应在100KB-500KB之间

  3. 使用浏览器缓存

    • 清除浏览器缓存
    • 使用隐私模式测试

解决方案：

问题：CORS 错误

症状：

排查步骤：

  1. 检查CDN域名配置

    • 确认CDN正确设置CORS头
    • 查看响应头是否包含 Access-Control-Allow-Origin

  2. 检查HTTPS/HTTP

    • 确认协议匹配
    • 混合协议可能导致CORS问题

解决方案：

显示问题

问题：字体显示不正确

症状：

排查步骤：

  1. 检查font-family名称

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

  2. 检查字符支持

    • 确认字体包含所需字符
    • 查看字体字符集说明

  3. 检查字体加载顺序

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

解决方案：

问题：字体模糊或锯齿

症状：

排查步骤：

  1. 检查字体格式

    • 确认使用WOFF2格式
    • WOFF2提供更好的渲染质量

  2. 检查浏览器设置

    • 查看浏览器字体渲染设置
    • 尝试调整字体平滑选项

  3. 检查屏幕分辨率

    • 高分辨率屏幕可能需要调整
    • 使用媒体查询优化

解决方案：

性能问题

问题：页面加载缓慢

症状：

排查步骤：

  1. 检查引用的字体数量

    /* 避免引用过多字体 */
@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");

  2. 检查字体文件大小

    • 查看Network标签中字体文件大小
    • 确认字体已进行拆包优化

  3. 检查网络连接

    • 测试网络速度
    • 确认CDN节点响应正常

解决方案：

问题：字体闪烁

症状：

排查步骤：

  1. 检查font-display设置

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

  2. 检查字体加载顺序

    • 确认字体CSS优先加载
    • 避免字体加载延迟

解决方案：

兼容性问题

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

症状：

排查步骤：

  1. 检查浏览器版本

    • 确认IE版本
    • 千字网CDN不支持IE浏览器

  2. 检查字体格式

    • WOFF2格式不被IE支持
    • 需要使用WOFF或EOT格式

解决方案：

问题：移动端显示异常

症状：

排查步骤：

  1. 检查媒体查询

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

  2. 检查viewport设置

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

解决方案：

网络问题

问题：无法访问CDN域名

症状：

排查步骤：

  1. 检查DNS解析

    # Windows
nslookup hanzi.itedev.com

# Mac/Linux
dig hanzi.itedev.com

  2. 检查网络连接

    • 确认网络连接正常
    • 尝试访问其他网站

  3. 检查防火墙设置

    • 确认防火墙未阻止CDN域名
    • 检查代理设置

解决方案：

问题：间歇性连接失败

症状：

排查步骤：

  1. 检查网络稳定性

    • 测试网络连接稳定性
    • 查看丢包率

  2. 检查CDN节点状态

    • 确认CDN节点运行正常
    • 查看CDN状态页面

解决方案：

诊断工具

浏览器开发者工具

使用方法：

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

关键信息：

在线字体检测工具

推荐工具：

获取帮助

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

  1. 查看其他文档

  2. 联系支持

    • 邮箱：exyone.dev@icloud.com
    • 提供详细的错误信息和环境信息

  3. 报告问题

    • 描述问题症状
    • 提供复现步骤
    • 附上错误截图