配置指南

本指南详细介绍千字网CDN的各种配置选项和参数说明。

基础配置

字体引用

千字网CDN提供两种引用方式：

方式一：单字体引用（推荐）

css

@import url("https://hanzi.itedev.com/fonts/字体文件夹/result.css");

优点：

加载速度快
带宽占用小
精确控制字体

方式二：全字体引用（不推荐）

css

@import url('https://hanzi.bluu.pl/main.css');

缺点：

加载所有字体，速度慢
带宽占用大
不适合生产环境

域名选择

千字网CDN提供多个域名：

域名	说明	推荐度
`https://hanzi.itedev.com`	加速域名，速度快	⭐⭐⭐
`https://hanzi.bluu.pl`	备用域名（仅可在Codeberg Pages中使用）	⭐
`https://hanzi.qzz.io`	Cloudflare 代理	⭐⭐⭐

推荐：优先使用 hanzi.itedev.com，速度最快。

高级配置

font-display 属性

控制字体加载时的显示行为：

css

@font-face {
    font-family: '字体族名';
    font-display: swap;
}

参数值：

值	说明	使用场景
`auto`	浏览器默认行为	通用场景
`block`	字体加载前不显示文本	关键标题
`swap`	立即显示后备字体，加载后替换	正文文本（推荐）
`fallback`	短时间显示后备字体，超时后使用默认字体	平衡方案
`optional`	字体加载快则使用，否则使用默认字体	装饰性字体

示例：

css

/* 标题使用 block */
h1, h2, h3 {
    font-family: 'Source Han Sans VF', sans-serif;
    font-display: block;
}

/* 正文使用 swap */
p, div {
    font-family: 'Source Han Sans VF', sans-serif;
    font-display: swap;
}

font-weight 属性

通过CSS控制字体粗细：

css

/* 常规（默认） */
.normal {
    font-weight: normal;
}

/* 粗体 */
.bold {
    font-weight: bold;
}

/* 数值控制 */
.thin {
    font-weight: 100;
}
.extra-bold {
    font-weight: 900;
}

常用值：

值	说明
`100`	极细
`200`	特细
`300`	细
`400` / `normal`	常规
`500`	中等
`600`	半粗
`700` / `bold`	粗
`800`	特粗
`900`	极粗

font-style 属性

控制字体样式：

css

/* 常规（默认） */
.normal {
    font-style: normal;
}

/* 斜体 */
.italic {
    font-style: italic;
}

/* 倾斜（模拟斜体） */
.oblique {
    font-style: oblique;
}

性能优化

预加载字体

提升字体加载速度：

html

<head>
    <!-- 预加载字体CSS -->
    <link rel="preload" href="https://hanzi.itedev.com/fonts/字体文件夹/result.css" as="style">
    
    <!-- 预加载字体文件 -->
    <link rel="preload" href="https://hanzi.itedev.com/fonts/字体文件夹/xxx.woff2" as="font" crossorigin>
    
    <link rel="stylesheet" href="style.css">
</head>

字体子集优化

千字网CDN已自动进行字体拆包，只包含常用字符。

优化建议：

只引用页面实际使用的字体
避免重复引用相同字体
使用 font-display: swap 提升体验

缓存策略

千字网CDN使用标准的HTTP缓存头：

CSS文件：缓存 1 小时
字体文件：缓存 1 年

建议：

生产环境使用长期缓存
开发环境使用 Cache-Control: no-cache

兼容性配置

浏览器兼容性

千字网CDN使用 WOFF2 格式，支持所有现代浏览器：

浏览器	最低版本	支持情况
Chrome	36+	✅ 完全支持
Firefox	39+	✅ 完全支持
Safari	10+	✅ 完全支持
Edge	14+	✅ 完全支持
IE	所有版本	❌ 不支持

字体回退方案

设置字体回退，确保兼容性：

css

body {
    font-family: 'Source Han Sans VF', 
                 'PingFang SC', 
                 'Microsoft YaHei', 
                 sans-serif;
}

回退顺序：

千字网CDN字体
系统中文字体
系统默认无衬线字体

移动端优化

针对移动设备的优化：

css

/* 移动端使用更小的字体文件 */
@media (max-width: 768px) {
    body {
        font-family: 'Source Han Sans VF', sans-serif;
        font-size: 16px;
    }
}

/* 桌面端使用标准字体 */
@media (min-width: 769px) {
    body {
        font-family: 'Source Han Sans VF', sans-serif;
        font-size: 18px;
    }
}

配置示例

完整配置示例

css

/* 引用字体 */
@import url("https://hanzi.itedev.com/fonts/Source+Han+Sans+VF/result.css");

/* 全局设置 */
* {
    box-sizing: border-box;
}

body {
    font-family: 'Source Han Sans VF', 'PingFang SC', 'Microsoft YaHei', sans-serif;
    font-size: 18px;
    line-height: 1.6;
    color: #333;
}

/* 标题设置 */
h1, h2, h3, h4, h5, h6 {
    font-family: 'Source Han Sans VF', sans-serif;
    font-weight: bold;
    margin-top: 1.5em;
    margin-bottom: 0.5em;
    font-display: block;
}

/* 正文设置 */
p {
    font-family: 'Source Han Sans VF', sans-serif;
    margin-bottom: 1em;
    font-display: swap;
}

/* 代码设置 */
code, pre {
    font-family: 'Source Han Sans VF', monospace;
    background-color: #f5f5f5;
    padding: 0.2em 0.4em;
    border-radius: 3px;
}

/* 引用设置 */
blockquote {
    font-family: 'Source Han Sans VF', sans-serif;
    border-left: 4px solid #333;
    padding-left: 1em;
    margin: 1em 0;
    color: #666;
}

常见配置问题

字体没有生效？

检查 font-family 名称是否正确
确认字体文件可以访问
查看浏览器控制台是否有错误
清除浏览器缓存重试

加载速度慢？

使用加速域名 https://hanzi.itedev.com
检查网络连接
使用 font-display: swap
考虑预加载字体

兼容性问题？

确认浏览器版本
设置字体回退方案
测试不同浏览器

更多问题请参考故障排查。

下一步

阅读使用教程了解基础用法
查看最佳实践优化配置
遇到问题？参考故障排查

配置指南 ​

基础配置 ​

字体引用 ​

方式一：单字体引用（推荐） ​

方式二：全字体引用（不推荐） ​

域名选择 ​

高级配置 ​

font-display 属性 ​

font-weight 属性 ​

font-style 属性 ​

性能优化 ​

预加载字体 ​

字体子集优化 ​

缓存策略 ​

兼容性配置 ​

浏览器兼容性 ​

字体回退方案 ​

移动端优化 ​

配置示例 ​

完整配置示例 ​

常见配置问题 ​

字体没有生效？ ​

加载速度慢？ ​

兼容性问题？ ​

下一步 ​