文档 · 更新于 2026-09-23

接入文风字体

一行 CSS 就能在网页中使用中文字体。公开字体走 cn.windfonts.com 的动态接口或拆包路径；正式站点建议创建项目、绑定域名，并核对每款字体的授权范围。卡住时先看常见问题。

1在字体库挑字体，看字重与授权 2复制字体页「使用」区的代码放进 <head> 3在 CSS 里写 font-family: "wenfeng-{slug}" 4上线前创建项目、绑定域名、子集化减体积

CDN 地址规则

对外地址一律用 CDN 域名 cn.windfonts.com（可切香港 / 国际节点）。字体页「使用」区在动态与静态之间切换；本站预览另走拆包对象路径。

动态（推荐嵌入）

与 Google Fonts 类似，用查询参数指定字体。字体页默认给出这种地址，主机是当前 CDN 节点：cn.windfonts.com、hk.windfonts.com、en.windfonts.com。复制出去的地址不要写成 app.windfonts.com；/api/css 以后由反代重写到上游。参数一律小写：family 用 wenfeng-{slug}；weight 用字重名；子集用 subset（full 完整，zh 中文，zh-common 常用字，en 西文）。version 现网不认。

https://cn.windfonts.com/api/css?family={family}&weight={weight}&subset={subset}

https://cn.windfonts.com/api/css?family=wenfeng-albbpht&weight=heavy&subset=full

多款可写在同一条里，family 用竖线 | 分隔；该请求的 weight 对各款共用。需要不同字重时拆成多条 <link>。

https://cn.windfonts.com/api/css?family=wenfeng-albbpht|wenfeng-ibmps&weight=regular&subset=full

返回 CSS 里的 font-family 常为 windfonts-{slug}，页面上请同时写 wenfeng-{slug}。

拆包路径（预览真源）

OSS 上按族 / 字重 / 版本拆好的 result.css，与动态接口读同一批对象。本站样张优先走这条；也可直接 <link>，跨域头已放开。

https://cn.windfonts.com/fonts-packages/{Normalized}/{Weight}/{version}/result.css

https://cn.windfonts.com/fonts-packages/Albbpht/Heavy/full/result.css

{Normalized}：目录归一化名（元数据 normalized），如 Albbpht。
{Weight}：包内字重目录，保留大小写（Regular、Heavy…）。
{version}：full、zh、zh-common、en。没有该目录时这条 404，预览会改走完整包。

动态接口和拆包直链都写在 CDN 域名上。动态是 /api/css，拆包是 /fonts-packages/…/result.css。

静态（兼容旧嵌入）

历史小写路径，多数已停更；新项目勿再当作真源。每个字重一份 CSS：

https://cn.windfonts.com/wenfeng/fonts/{slug}/{weight}/web/index.css

{slug}：族名去掉 wenfeng-，如 albbpht。
{weight}：小写字重名，见对照表。
index.css 完整；zh_index.css 中文子集，见子集化。

三类地址的 CSS 都按 Unicode 区间切分片；浏览器只下载页面用到的 woff2。

用 <link> 引入

放入页面 <head>。先 preconnect 再拉 CSS，可省一次 DNS + TLS 往返。免费提供的字体请保留授权标注注释。

<!-- 此中文网页字体由文风字体（Windfonts）免费提供，您可以自由引用，请务必保留此授权许可标注 https://wenfeng.org/license -->
<link rel="preconnect" href="https://cn.windfonts.com" crossorigin>
<link rel="stylesheet" href="https://cn.windfonts.com/api/css?family=wenfeng-albbpht&weight=regular&subset=full">

拆包路径同一款：

<link rel="stylesheet" href="https://cn.windfonts.com/fonts-packages/Albbpht/Regular/full/result.css">

静态旧路径（仅兼容）：

<link rel="stylesheet" href="https://cn.windfonts.com/wenfeng/fonts/albbpht/regular/web/index.css">

需要多个字重就多写几行 <link>，每个字重一份 CSS；字体页「使用」区与选字袋可一次生成多款、多字重的合并代码。

用 @import 引入

写在 CSS 文件顶部（@import 必须位于其他规则之前）。相比 <link> 会晚一个解析阶段，首屏字体优先用 <link>。

@import url('https://cn.windfonts.com/fonts-packages/Ibmps/Regular/full/result.css');
@import url('https://cn.windfonts.com/fonts-packages/Ibmps/Bold/full/result.css');

在 CSS 中使用

CSS 声明的 font-family 请用目录标识 wenfeng-{slug}。包内 CSS 可能写 windfonts-{slug}，页面上两种都写最稳。始终保留系统中文回退，避免加载期间空白。

.title {
  font-family: "wenfeng-albbpht", "windfonts-albbpht",
               "PingFang SC", "Microsoft YaHei", sans-serif;
  font-weight: 400;
}

同一页面同时引入一款字体的多个字重时，请在 font-weight 上区分；如果你自己拼接 CSS，需要为每个字重的 @font-face 补上对应 font-weight，并去掉 local()，否则本机同名字体或后加载的字重会盖住前者。项目 CDN 生成的 CSS 已处理好这一点。

npm 与框架

现代前端工作流用 @windfonts/loader 按需注入，并拿到加载状态（loading / loaded / error）。包与示例见开源仓 Windfonts/font-packages。

安装

npm install @windfonts/loader

一次加载多款 / 多字重

import { loadFonts, loadFont } from '@windfonts/loader';

/* 多款 */
const status = await loadFonts([
  { family: 'wenfeng-albbpht', weights: ['regular', 'bold'], version: 'zh' },
  { family: 'wenfeng-ibmps', weights: ['regular'], version: 'full' }
], { display: 'swap' });

/* 单款简写 */
await loadFont('wenfeng-albbpht', { weights: ['regular', 'heavy'], subset: 'zh' });

React

import { useWindfonts } from '@windfonts/loader/react';

function Title() {
  const { status, error } = useWindfonts([
    { family: 'wenfeng-albbpht', weights: ['bold'] }
  ]);
  if (status === 'error') return <p>字体加载失败：{String(error)}</p>;
  return (
    <h1 style={{ fontFamily: '"wenfeng-albbpht", "PingFang SC", sans-serif', fontWeight: 700 }}>
      文风字体
    </h1>
  );
}

Vue

用 useWindfonts() composable，返回同一份状态对象（status / error）。

WordPress 站点可直接用文派的字体插件，在后台选字即可。纯静态页仍推荐 <link> + CDN，不必强行上 npm。

REST API 概述

数据面提供 RESTful JSON API，用于字体查询、分类与品牌浏览。基址：

https://app.windfonts.com/api

所有响应均为 JSON，统一信封：

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

CSS 嵌入仍走 cn.windfonts.com（见CDN 地址规则）；本段只描述元数据 API。

集成约定（摘要）：

信封固定 { "code", "message", "data" }；成功 code === 200。
匿名日配额约 100 次 —— 勿在每个页面打开时拉全库；列表热度用构建期同步，详情可按需打单款。
浏览器跨域读正文需要响应带 CORS；未放开前，公开站详情计数可能仍显示本地数字。
投递三轨（css / 项目 / 鉴权子集）与增量 API 分期见仓库计划稿 docs/plans/2026-09-24-api-surface-value.md。

认证与白名单

API 用密钥管理访问与配额。多数 GET 支持匿名，但有严格日限流（默认约 100 次/天）。正式集成请申请 API Key 以提高配额。

白名单免密钥

请求域名加入白名单后，可免 API Key 访问字体 API，且不计入日配额。白名单需完全匹配规范化后的 hostname（不支持通配），由管理员配置。

浏览器跨域/同域请求通常会自动带 Origin；服务端调用须自行附带。
日配额：白名单流量不消耗日配额。
分钟限流：默认约 600 次/分钟（可由服务端配置调整）。

项目 CDN 的「域名白名单」（见域名白名单）管的是字体文件分发；此处白名单管的是 REST 元数据 API，二者用途不同。

传递 API Key

任选其一（推荐 Header）：

Authorization: Bearer wf_live_...
# 或
X-API-Key: wf_live_...

# Query（不推荐写进前端公开页面）
GET /api/fonts?apiKey=wf_live_...

字体接口

`GET /api/fonts`

分页列表，支持筛选与排序。

参数	说明
page	页码，默认 1
size	每页条数，默认 20
category	分类 ID / slug
brand	品牌 ID
search	关键词
sort	`name` · `createdAt` · `viewCount`

GET https://app.windfonts.com/api/fonts?page=1&size=20&sort=viewCount

{
  "code": 200,
  "data": {
    "total": 100,
    "page": 1,
    "pageTotal": 5,
    "dataList": [
      {
        "id": "uuid",
        "name": "思源黑体",
        "fontFamily": "Source Han Sans",
        "category": { "name": "无衬线体" },
        "brand": { "name": "Adobe" }
      }
    ]
  }
}

`GET /api/fonts/:family`

单款详情，路径可为字体 ID 或族名 / slug（如 albbpht、qtxtt）。

GET https://app.windfonts.com/api/fonts/albbpht

现网常见字段（集成方优先依赖下列稳定项；其余可能随同步演进）：

字段	说明
id · name · fontFamily	标识与名称（嵌入短码以公开站 `family=wenfeng-*` 为准）
weights	字重对象 / 列表
category · brand	分类、品牌
languages · useCases	语言与场景标签
viewCount · downloadCount · apiCallCount	浏览 / 下载 / CSS 拉取计数

字符表：GET /api/fonts/:id/analysis（路径优先 normalizedName，如 Ibmps；无分析文件时 404）。公开站查字默认用本地数据；详情「字符表」工具栏可点对照表按需请求（限流时回退同源 fonts-packages/metadata/font-analysis.json）。现网 analysis 覆盖目录 471 族（CSS unicode-range 重建）；详情缺字判定真源仍是分包 CSS 的 unicode-range。

包体预估：GET /api/fonts/:id/estimate?subset=（预计算 CSS 档字节清单）；详情嵌入预算条优先用清单，无则启发式。

分类与品牌

`GET /api/categories`

全部分类列表。

GET https://app.windfonts.com/api/categories

{
  "code": 200,
  "data": [
    {
      "id": "uuid",
      "name": "无衬线体",
      "slug": "sans-serif",
      "description": "现代简洁的字体风格"
    }
  ]
}

`GET /api/brands`

全部品牌（厂商）列表，字段结构与分类类似，用于筛选与厂商页。

GET https://app.windfonts.com/api/brands

子集化

中文字体整包常在 5–15 MB。子集化只保留会出现的字，体积可减少 90% 以上。

方式	适用	在哪里
预制 · 完整 `…/full/result.css`	正文不固定、需要生僻字	公开 CDN · fonts-packages
预制 · 中文常用 `…/zh-common/result.css`	常见中文内容	公开 CDN · fonts-packages
静态旧路径 `zh_index.css`	兼容旧嵌入；多数已停更	`/wenfeng/fonts/…/web/`
按文字	标题、品牌名、固定文案；体积以 KB 计	控制台 · 子集化工作台
按常用字 3500 / 7000	正文不固定但不需要生僻字的站点	控制台 · 子集化工作台
按编码范围	多语言、自定义字集	控制台 · 子集化工作台

https://cn.windfonts.com/fonts-packages/Albbpht/Regular/zh-common/result.css

控制台生成的自定义子集作为项目版本发布，走项目 CDN 地址，改子集不需要改嵌入代码。

按文字即时切

标题、品牌名这类固定文案可以不建项目，用密钥直接按文字要一版。密钥在控制台「设置」。地址里的字重用字重名，不用数字。

curl -X POST https://cn.windfonts.com/v1/subset \
  -H "Authorization: Bearer $WINDFONTS_KEY" \
  -d family=wenfeng-albbpht \
  -d weight=regular \
  --data-urlencode text="让中文字体在网页上，一行代码可用。"

font-display

控制字体加载期间文字如何呈现。CDN 的 CSS 默认 swap；项目设置里可统一指定，项目 CDN 会按设置生成。

swap（默认）：先用回退字体显示，加载完成后替换。首屏最快，有一次重排。
block：短暂隐藏文字等待字体，适合品牌标题。
fallback / optional：网络慢时放弃替换，保证阅读稳定。

preload 与 preconnect

关键字体（首屏标题）可在 <head> 顶部预加载 CSS，再由 CSS 拉字体分片；配合 preconnect 效果最好。不要 preload 字体文件本身——分片由 unicode-range 决定，浏览器比你更清楚要哪几片。

<link rel="preconnect" href="https://cn.windfonts.com" crossorigin>
<link rel="preload" as="style" href="https://cn.windfonts.com/fonts-packages/Albbpht/Bold/full/result.css">
<link rel="stylesheet" href="https://cn.windfonts.com/fonts-packages/Albbpht/Bold/full/result.css">

缓存与更新

字体分片文件名含内容哈希，可长期缓存；CSS 短缓存（约 10 分钟），字体更新版本时只需 CSS 刷新。项目 CDN 地址指向项目「当前版本」，发布或回滚后 CSS 自动切换，无需改代码。

项目与项目 CDN

项目是「一组字体 + 一组域名 + 一份设置」的发布单元。登录控制台新建项目，从字体库或选字袋把字体加进来，逐款设定字重与子集，发布后得到项目地址：

https://cn.windfonts.com/p/{project-slug}/index.css

一份 CSS 包含项目内全部字体与字重，已按项目设置处理 font-display 与 font-weight。
免费版 1 个项目 / 3 个域名；专业版 10 个项目、域名不限、月流量 200 GB，见定价。

域名白名单

项目绑定的域名决定字体文件对谁返回。白名单外的请求会被拒绝，并记入控制台「域名 › 未授权访问」。

支持精确域名与通配 *.example.com（不含根域名）；localhost 与 127.0.0.1 默认允许。
新增域名需验证，两种方式任选：DNS TXT _windfonts.example.com → "windfonts={project-id}"，或在站点根目录放置 /.well-known/windfonts-verify.txt，内容为项目 ID。
公开 CDN（cn.windfonts.com）不校验域名，但有限流；正式站点请走项目 CDN。

版本与回滚

项目每次改动（增删字体、修改子集、切换字重）都生成一个新版本，记录体积与说明；嵌入代码指向项目而不是具体版本，发布即生效。出问题时在项目「版本」标签回滚——回滚以旧版内容生成新版本，历史不丢。

用量与统计

控制台「用量」按项目、字体、字重、域名四个维度统计请求数与流量，另有成功下发、缓存命中、被拒三类占比，以及字体加载中位时间（仅白名单域名）。数据延迟约 5 分钟，支持 7 / 30 / 90 天与 CSV 导出。点任一字体可看各字重用量，便于从项目里移除很少用到的字重。

上传自有字体

支持 .ttf .otf .woff .woff2。上传时自动解析名称、字重、字符数，生成分片与全部格式，之后与库内字体一样加入项目、子集化。你必须拥有该字体的合法授权，上传即视为承诺；自有字体只通过项目 CDN 分发，不进入公开字体库。约定见上传条款。

地址参数

段 / 参数	说明	示例
`family`	动态查询：`wenfeng-{短码}`，多款用 `\|`	wenfeng-albbpht
`weight`	动态查询：小写字重名	regular · heavy
`subset`	动态查询：换包认此参数（与预计算档对齐）	en · zh-common · zh · full
`version`	兼容双写：应与 `subset` 同值；现网 vault 不认其换包	同 subset
`fallback`	谱系补全第二款；服务端裁切 unicode-range 只留主款缺口	wenfeng-syhtsc
`fallbackWeight`	补全款字重；缺省与主款对齐	regular
`localeFallback`	简繁兄弟：`auto`/`sc`/`tc`；有配对且未传 `fallback` 时展开	auto
`{Normalized}`	拆包路径：目录归一化名	Albbpht · Hckht · Ibmps
`{Weight}`	拆包路径：包内字重目录，保留大小写	Regular · Heavy · Normal
`{slug}`	静态旧路径：族名去掉 `wenfeng-`	albbpht · syhtcjk
`font-family`	页面推荐写法；包内或为 `windfonts-*`	"wenfeng-albbpht"

https://cn.windfonts.com/api/css?family=wenfeng-albbpht&weight=regular&subset=full
https://cn.windfonts.com/fonts-packages/{Normalized}/{Weight}/{full|zh-common}/result.css
https://cn.windfonts.com/wenfeng/fonts/{slug}/{weight}/web/{index|zh_index}.css

字重名对照

地址里用字重名而不是数字；CSS 里用数字 font-weight。拆包路径的 {Weight} 保留大小写（如 Regular）；旧静态路径用小写。个别字有自有命名（Normal、ExtraBold），以字体页为准：

地址段（小写 / 包内）	font-weight	地址段	font-weight
thin · Thin	100	medium · Medium	500
extralight · ExtraLight	200	semibold · SemiBold	600
light · Light	300	bold · Bold	700
regular · Regular · normal	400	heavy · Heavy · extrabold	800
text · Text	450	black · Black	900

选字袋

在字体库或字体页「加入选字袋」，到选字袋统一预览、比较，并一次生成多款字体的合并嵌入代码。登录后可把选字袋整体添加到某个项目。选字袋存在浏览器本地。

许可与常见问题

许可注意、类型对照，以及嵌入 / 白名单 / 授权边界，已各自成页。

许可说明常见问题