# 文派字库

文派字库🀄️（WPFonts）是文风字体的官方 WordPress 插件：系统字体默认可用；可选开启文风云，或把文风已切好的字体包装到本站。

# 文派字库是什么

> 适合谁看：在 WordPress 站点上想用系统字体或文风网页字体的站长。

文派字库（WPFonts）是文风字体的官方 WordPress 插件。装上之后，中日韩英系统字体默认可用；需要网页字体时，再开文风云，或把文风已切好的字体包装到本站。

文档按插件 `Stable tag` 叙述能力（目前跟踪到 `2.0.0-rc.11` 一带）。你站点插件列表里的版本可能更旧或更新，以本机为准；演示站也不保证与文档同步。正式版要等 CI 和文风 Key 就绪后再定。

产品页：[wpcy.com/fonts](https://wpcy.com/fonts)（资料口；真源文档即本书）  
代码仓库：[github.com/WenPai-org/wpfonts](https://github.com/WenPai-org/wpfonts)

## 默认就有什么

启用插件后，字体库里会按语种出现系统字体栈：**系统 · 中文 / 英文 / 日文 / 韩文**。自 **2.0.0-rc.7** 起，设置页有四个勾选框（默认全开）；**取消勾选的语种不会登记进字体库**。多数站点只靠系统栈就够用，不必立刻开网页字体。

后台入口：**设置 → 文派字库**。


## 设置怎么看（rc.10–rc.11）

设置页默认是 **简单**：

- 系统字体语种开关；
- **中文回退 / 正文 / 标题**（装好字体包后，可在这里指定中文用法）；
- 文风云开关（默认关）。

需要 API Key、项目名、服务器区域、字符范围、目录刷新、手工字体名等时，切到 **高级**。文风云关闭时，这些云相关字段保持折叠，避免空表单干扰。

后台页脚左侧为「文派字库（WPFonts）· 版本号」，右侧为「反馈」。

## 两条网页字体路径

| 路径 | 做什么 | 默认 |
|---|---|---|
| **文风云** | 前台按已确认的云字脸各挂一条文风服务器样式链接（`wenfeng-*`） | 关闭 |
| **文风字体包** | 把文风已切好的 zip 装到本站，由本站托管 | 不装则无 |

两条路互不影响。可以只用其一，也可以一起用。字体库集合名：启用包为「**文风字体**」（英文 Windfonts）；云字为「**文风云**」（不变）。设置里仍称可装包为「文风字体包」。自 **2.0.0-rc.8** 起，安装本地包时会尽量把 `WF-*` / `windfonts-*` 对齐成同一套 `wenfeng-*` 短名（详见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)）。

本站包装进字体库后：族名是 `wenfeng-*`；列表显示名约定为「文风·{原名}」。若你看到的仍是短码，请升级到含显示名修复的构建后对该包重新安装 zip。

## 版本能力（rc.4–rc.12）

| 能力 | 自哪个版本 |
|---|---|
| 启用包装进字体库；已确认文风云脸以「文风云」登记 | **2.0.0-rc.4** |
| 块检查器面板「文派字库」（现网可见） | **2.0.0-rc.4** 引入；**2.0.0-rc.6** 起侧栏可见 |
| 启用包 / 已确认脸 **自动写入用户全局样式**（不改主题；卸载不删 GS） | **2.0.0-rc.5** |
| **多张**已确认文风云脸；系统语种可开关；包健康中文说明；工具页导出/导入（不含 Key） | **2.0.0-rc.7** |
| 装包时族名 / 包 id / 字体库与 GS slug 对齐 `wenfeng-*`；`local.css` 改写；旧包不改目录 | **2.0.0-rc.8** |
| 设置：中文回退 / 正文 / 标题 | **2.0.0-rc.10** |
| 设置：简单默认 + 高级渐进展示；工具在「有本站包且文风云关」时首推本站字体包；装包预览用 local.css 族名；去掉装包/工具页切字说教卡；页脚版本 + 反馈 | **2.0.0-rc.11** |
| 字体库 / 装包列表显示名优先「文风·{原名}」；短码只作 family / 包 id | **2.0.0-rc.12**（待发；合入前仍可能只见短码） |

两条用法请分清：侧栏「文派字库」只改**当前块**；已启用的文风字体包与已确认的文风云脸进入**全站**样式，再到 **外观 → 编辑器 → 样式 → 排版**。细节见[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)。

## 插件明确不做的事

插件不切字，也不写 theme.json。网页字体包请使用文风已经准备好的 zip；装包页只接收可用的样式与 woff2。更多说明见[《常见问题》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-faq)「插件会切字吗？」。

## 接下来读什么

- 安装：[《安装与运行要求》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-install)
- 远程嵌入：[《文风云》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-yun)
- 本站托管：[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)
- 字体库与排版：[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)
- 排障：[《常见问题》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-faq)

# 安装与运行要求

> 适合谁看：准备安装文派字库，想先确认环境的人。

## 运行要求

- WordPress **6.5** 或更新
- PHP **7.4** 或更新
- 字体库那条路径需要**块主题**（系统字体、字体库选用才完整可用）

## 怎么装

可从文派叶子、菲码，或 GitHub 发布包安装 zip，再在插件列表里启用。文档按 `Stable tag` 叙述（目前跟踪到 `2.0.0-rc.11` 一带）；**以你站点插件列表显示的版本为准**。

启用后，后台出现 **设置 → 文派字库**。系统字体无需额外配置（四个语种勾选默认全开）；要网页字体时，再去开文风云或安装文风字体包。

## 装完先看哪里

1. 打开 **设置 → 文派字库 → 概览**，确认插件已启用。设置默认在「简单」。只要系统字体或本站字体包时，不必先填文风 API Key。
2. 块主题下，到编辑器字体库里应能看到 **系统 · 中文 / 英文 / 日文 / 韩文**（若某语种被取消勾选则不会出现）。
3. 需要指定中文用法时，在简单设置里看 **中文回退 / 正文 / 标题**。需要网页字体时，再读[《文风云》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-yun)或[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)（装包命名对齐见该页 **rc.8** 说明）。
4. 站点迁移或备份设置：见 **设置 → 文派字库 → 工具**（导出不含 API Key），说明在[《常见问题》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-faq)。

# 文风云

> 适合谁看：想让站点从前台加载文风远程网页字体的站长。

文风云默认**关闭**。开启并保存后，前台只为**已确认可用**的云字脸挂 allowlist 样式链接；网页里不会出现 API Key。自 **2.0.0-rc.7** 起，可以同时保存**多张**已确认的 `wenfeng-*` 脸。

只使用本站字体包时，保持文风云关闭即可，见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)。

手工贴 `<link>` 也能接文风，见文风用户文档[《网页字体引用与 CDN 接入》](https://docs.cocobook.com/books/windfonts/page/cdn)。用插件可以少拼地址、少抄字体名。

## 开启前准备

1. 打开 **设置 → 文派字库 → 设置**。
2. 在 **简单** 打开「文风云」并保存。简单视图下只会多出「选用字体」。
3. 切到 **高级**，再选文风服务器（仅 `cn.windfonts.com`、`hk.windfonts.com`、`en.windfonts.com`）、字符范围；需要时填写项目名与 API Key（可在工具页验证）。
4. 从本机目录确认一张或多张 `wenfeng-*` 脸（rc.7 起可多张）。

未确认任何脸、且未填可用的字体名/项目名时，前台不会挂远程样式链接。公开 `/api/css` 没有字体名时返回的不是 CSS。公开样式若 404，插件不会嵌入，也不会宣称已加载。

## 多张已确认脸（rc.7）

- 字体库集合「**文风云**」与块侧栏「文派字库」会**列出全部**已确认脸。
- 从 **2.0.0-rc.6** 只存单脸的站点升级后，**仍保留那张脸**，可继续追加。
- 从前台按脸各输出一条 allowlist 样式链接（仍不把 Key 打进 HTML）。
- **去掉某一张脸**时，只移除本插件为该脸写入的全局样式条目；其它脸与其它 GS 不动。

## 启用之后（样式确认可用）

文风云样式**确认可用**后（`2.0.0-rc.4` 起；多脸自 **rc.7**）：

1. 对应字体脸进入 WordPress **字体库**，集合名是「文风云」。
2. 自 **2.0.0-rc.5** 起，还会**自动同步进用户全局样式**，可在 **外观 → 编辑器 → 样式 → 排版** 选用。
3. 未填字体名/项目名、或 Key 未通过、样式未确认时：不加载对应前台链接，也不进该集合 / 排版同步。

不必再到字体库里手动「安装」一遍。侧栏只改当前块；全站排版走全局样式。见[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)。

若同一张字也以本站包安装：自 **2.0.0-rc.8** 起，能识别的包内族名会对齐成同一 `wenfeng-*` 短名，选型时更不容易和云字脸对不上。见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)。

## 两条地址形态

| 场景 | 地址形态 |
|---|---|
| 默认轨（公开） | `/api/css`，需要字体名 + 字符范围 |
| 进阶（项目） | `/p/{项目名}`，域名白名单在文风控制台配置 |

填了项目名后，前台改用项目样式；公开地址可以不填字体名。

## 文风 API Key

Key 只在服务器上请求 `https://app.windfonts.com/api/key/status` 做校验。它不进入网页，也不写进样式地址，也**不会**出现在工具页的导出文件里。

Key 无效时，按工具页提示处理；不要把 Key 贴进主题或页面 HTML。

## 字符范围（四档）

字符范围决定远程字体包大小。插件不在这里切字。

| 选项 | 说明 |
|---|---|
| 西文 | 体积最小，主要覆盖拉丁字符 |
| 常用中文（推荐） | 日常中文站点够用，体积适中 |
| 较全中文 | 生僻字更多，体积明显更大 |
| 全量 | 最大包，仅在确实需要时使用 |

## 字体目录

设置页目录来自本机 `catalog.json`（约在 `wp-content/uploads/wpfonts/`）。大约每月自动更新；也可点「更新字体目录」。打开设置页本身不会去打文风。

更新失败不会盖掉已有好快照。没有目录时仍可手填 `wenfeng-*` 字体名。

更细的目录行为见[《字体目录与选用》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-catalog)。

# 文风字体包

> 适合谁看：想把字体文件放在自己站点上、不从文风远程加载的站长。

把文风已经准备好的字体包 zip 装到本站，由本站托管。启用后可在全站样式与字体库里选用。集合名是「文风字体」。

切片包请到文风领取（开源目录或字体页的切片下载），不要把 CDN 分片当自托管源。主题里整夹引入 `fonts.css` 的做法见文风《用法》；本页只讲插件「字体包」装到本站。

## 怎么装

1. 打开 **设置 → 文派字库 → 字体包**。
2. 拖入（或选择）含样式与 woff2 的 zip。
3. 安装后按需 **启用**。未启用的包不会进前台。

装不上时：换一份含可用样式（如 `local.css`）和 woff2 的 zip 再试。

文件落在：

```
wp-content/uploads/wpfonts/packages/
```

## 预览（rc.11）

字体包页会按该包 `local.css` 里的 `font-family` 做样本预览（不是用包 id 硬猜）。停用的包在本页仍可预览。若缺少 `local.css`，提示「预览暂时不可用」，并参见下方包健康说明。

## 安装时的命名（rc.8 起）

装包时要分清两样东西：

| 用途 | 长什么样 | 用在哪 |
| --- | --- | --- |
| **CSS / 字体库 family** | `wenfeng-{short}`（小写短码） | `local.css`、排版选用、与文风云对齐 |
| **显示名**（给人看） | 收录名，约定写成 **「文风·」+ 原名**，例如「文风·玄宗体」 | 字体库列表、字体包页、工具页卡片 |

短码是技术 id；显示名不要写成短码本身。

### family 怎么定（rc.8）

插件会尽量把包内族名对齐成 `wenfeng-{short}`：

1. 先读包内 `meta.json` / `metadata.json` / `font.json` 的 `fontFamily`（或 `font_family`）
2. 若没有可用目录名，再读解压后 `result.css` 里第一条 `@font-face` 的 `font-family`

| 包内写法 | 登记结果（示例） |
| --- | --- |
| `WF-Fzss` | `wenfeng-fzss` |
| `windfonts-ibmps` | `wenfeng-ibmps` |
| 已是 `wenfeng-*` | 保持，仅规范为小写 |
| 两边都认不出 | 回退为 zip 文件名（如 `fzss-zhcommon.zip` → `fzss-zhcommon`） |

对齐成功时：包 id、字体库 slug、全局样式 slug 都用这个 `wenfeng-*`；写入的 `local.css` 会改 `@font-face` 的 `font-family`；`url()` 里的 woff2 **不改名**。

认不出、只能走 zip 名回退时：字体库 slug 可能仍带原来的 `wpfonts-pkg-` 前缀。

**已经装好的旧包目录不会被改写**；要得到 `wenfeng-*` 登记，请在含 rc.8 及以上的构建里重新安装该 zip。

### 显示名怎么定

约定对外显示为 **「文风·{原名}」**（中间用间隔号「·」）。原名来自包元数据或样式注释里的中文名；缺元数据时不应把 `wenfeng-xxxx` 短码直接当列表标题。

若你当前构建的字体库里仍只看到短码，请升级到含显示名修复的版本后，对受影响的包 **重新安装** 一次 zip（旧登记不会自动改名）。

### 短码以本机为准

目录收录名、演示站旧包、以及某次 zip 文件名，偶尔会对不齐同一短码。排查时以本站 **已登记** 的 `font-family` / 包 id 为准；不要手编短码去「对齐」别处看到的写法。

## 启用之后

启用文风字体包后（`2.0.0-rc.4` 起；命名对齐自 **rc.8**）：

1. 字体进入 WordPress **字体库**，集合名是「**文风字体**」（Windfonts）。 列表里应能区分显示名与 `wenfeng-*` 族名；选用排版时用族名，不要只抄显示文字。
2. 自 **2.0.0-rc.5** 起，还会**自动同步进用户全局样式**，可在 **外观 → 编辑器 → 样式 → 排版** 选用。
3. 未启用的包：不进前台，也不进该字体库集合 / 排版同步。

不必再到字体库里手动「安装」一遍。侧栏选用见[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)。

## 包健康说明（rc.7）

字体包页会用中文说明常见异常，例如：

- **缺少 local.css**：包目录里没有可用的本地样式入口。
- **没有可用的 woff2**：样式里找不到能加载的字体文件。
- **已启用但不会加载**：开关开着，但上述问题导致前台仍不会挂上该包。

注意：uploads 目录里**还有别的、未读到的包文件夹**，**不会**把本来健康的已登记包装成「坏包」。健康提示只针对插件已识别、正在管理的那几份。

## 和文风云的关系

- 与文风云开关**互不影响**。
- 可以只装包、不开文风云；也可以两边都开。
- 启用后的包，前台加载本站的 `local.css`，不依赖文风远程样式链接。
- 自 **rc.8** 起，能对齐的本站包与云字脸共用 `wenfeng-*` 短名，选型时更不容易对不上。

- 自 **2.0.0-rc.11** 起：已安装本站包且文风云关闭时，**工具**页会优先展示「本站字体包」状态（名称、使用中/已停用、样式是否可打开、前台样式地址），而不是先催填 API Key。

## 管理

每个包可以：

- **启用 / 停用**：控制是否对前台生效；停用后插件会只移除本插件写入的全局样式条目
- **删除**：卸掉本站这份文件（不影响文风侧的源包）

卸载插件时，默认不删已安装的文风字体包；需要的话在文件系统里自行清理 `uploads/wpfonts/packages/`。卸载也**不删除**用户全局样式，见[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)。

## 导出与导入（见工具页）

自 **2.0.0-rc.7** 起，可在 **设置 → 文派字库 → 工具** 导出 / 导入：已启用包的元数据 + 已确认的文风云脸。文件**不含** API Key；若整份文件里仍带有 Key，导入会**整份拒绝**。详见[《常见问题》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-faq)。

# 字体目录与选用

> 适合谁看：在设置里选字体名，或目录空白、更新失败时来排查的人。

设置页只读本机快照，不在打开设置时去请求文风。

## 快照在哪

路径大致是：

```
wp-content/uploads/wpfonts/catalog.json
```

结构形如：更新时间 + 字体列表；选用时写入的是 `fontFamily`（例如 `wenfeng-zhi-mang-xing`），不是别的字段。

## 何时更新

- WP-Cron 大约每 **30 天**自动拉一次目录并写成快照。
- 也可在设置里点「更新字体目录」立刻更新。
- 手动更新有约 **60 秒**冷却，避免连点打爆接口。
- 首装若还没有快照，会排队做一次立即刷新（打开设置页本身仍不会去打目录）。

## 失败时会怎样

更新失败**不会**盖掉已有好快照。你仍会看到上一份目录。

没有快照时，仍可手填 `wenfeng-*` 字体名；装好文风字体包的站点，也可以先走本站包，不必等目录。

## 选用写入什么

在设置里选中一款字后，保存的是 `fontFamily`。公开轨拼 `/api/css` 时用它；和目录里的显示名可能不一样，以 `wenfeng-*` 为准。

自 **2.0.0-rc.7** 起，可把多张目录脸确认为文风云脸；字体库「文风云」与侧栏会列出全部已确认项。详见[《文风云》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-yun)。

自 **2.0.0-rc.8** 起，安装本站文风字体包时也会尽量登记成同一套 `wenfeng-*` 短名，方便与目录 / 云字脸对上；详见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)。


## 显示名和短码

目录里的中文名（或「文风·…」）方便挑选；写入设置与拼公开样式时用的是 `fontFamily`（`wenfeng-*`）。  
个别演示站或旧包上的短码，可能和目录某一行不完全一致——以本机快照与已登记包为准，不要手改短码。

## 和「简单」设置的关系（rc.10–rc.11）

目录与「选用字体」主要服务 **文风云**（高级里更完整）。  
只使用本站字体包时：在 **简单** 设置里用中文回退 / 正文 / 标题指定用法即可；不必先更新目录或填写 Key。

# 编辑器与全局样式

> 适合谁看：想在块编辑器或全局样式里选用文派字库字体的站长。

自 **2.0.0-rc.4** 起，文派字库把已启用的文风字体包、以及目录里已确认可用的文风云字体脸，登记进 WordPress **字体库**；块检查器里也开始有一块名为「文派字库」的面板。自 **2.0.0-rc.5** 起，这些字体还会**自动写入用户全局样式**（`wp_global_styles`），可在 **外观 → 编辑器 → 样式 → 排版** 里看见，不必再到字体库里手动「安装」一遍。

正式版以发版说明为准；下文描述的是当前 **`2.0.0-rc.11`** 构建上的行为（兼容 rc.8 命名对齐，并含 rc.10 中文指定、rc.11 管理 UI）。

## 字体库与全局样式（rc.4–rc.11）

| 版本 | 行为 |
|---|---|
| **2.0.0-rc.4** | 已启用的文风字体包装进字体库集合「文风字体」（Windfonts）；目录已确认脸以「文风云」登记；字体库安装写入用户全局样式路径 |
| **2.0.0-rc.5** | 启用包、以及已确认的文风云脸，会**自动复制进用户全局样式**；在 **外观 → 编辑器 → 样式 → 排版** 可见 |
| **2.0.0-rc.6** | 块检查器面板「文派字库」**现网可见**（侧栏可见性修复） |
| **2.0.0-rc.7** | 可保存**多张**已确认文风云脸（字体库「文风云」与侧栏「文派字库」都会列出）；系统语种四勾选；帮助文案写清侧栏 vs 排版；包健康提示；工具导出/导入 |
| **2.0.0-rc.8** | 安装文风字体包时，能识别的族名对齐为 `wenfeng-*`；字体库 / 全局样式 slug 用该短名（不再套 `wpfonts-pkg-`）；写入的 `local.css` 同步改写；已装旧包不改目录 |
| **2.0.0-rc.10** | 设置可指定中文回退 / 正文 / 标题，便于全站中文排版选用 |
| **2.0.0-rc.11** | 管理界面：简单/高级；本站包优先的工具首屏；装包预览族名来自 local.css；页脚版本与反馈 |
| **2.0.0-rc.12**（待发） | 文风字体包在字体库中的显示名优先「文风·{原名}」；family / slug 仍为 `wenfeng-*` |

要点：

- **不修改主题文件**。站长自有的字体、颜色等全局样式条目不受影响。
- 系统字体栈（**系统 · 中文 / 英文 / 日文 / 韩文**）默认证入字体库；在设置里取消某语种勾选后，该语种**不再登记**。
- 前台访客请求**不会**写入全局样式 post。
- 选用时请用 `wenfeng-*` 这类 `fontFamily`（本站包在 **rc.8** 起尽量与此一致），不要只抄显示名。
- 字体库里看到的「文风·…」是显示名；真正写入样式的仍是 `wenfeng-*` 族名。两者不要混用。

## 两条路径请分清（帮助说明）

自 **2.0.0-rc.7** 起，插件帮助区写死这两条：

1. **块侧栏「文派字库」**：只作用于**当前块**的字族选择；不会拉整站目录去改主题。
2. **已启用的文风字体包** + **已确认的文风云脸** → 进入**全站**用户全局样式 → 再到 **外观 → 编辑器 → 样式 → 排版** 选用。

两者互补，不要混成「侧栏等于全站排版」。

## 块侧栏「文派字库」

rc.4 起，块检查器里增加了名为 **「文派字库」** 的面板；rc.6 起现网可见。自 **rc.7** 起，面板会列出：

- 已启用的文风字体包（组名「文风字体」）
- **每一张**已确认的文风云脸（组名「文风云」）

选中后只改当前块的 typography 字族。

## 生命周期：停用、删除、卸载

| 操作 | 对全局样式的影响 |
|---|---|
| 停用或删除文风字体包 | **只移除本插件为该包写入的条目**；其它全局样式保留 |
| 从已确认列表里去掉一张文风云脸 | **只移除本插件为该脸写入的条目**；其它云脸与其它 GS 保留 |
| 卸载插件 | 清设置项、目录快照等插件数据；**不删除**用户全局样式（`wp_global_styles`） |

若卸载后排版里还指着已卸掉的字体，需要自己在站点编辑器里改回。

## 现在若看不到

1. **排版里没有自动同步的字体**：请升到含 **2.0.0-rc.5**（含）以上的构建，并确认文风字体包已启用，或至少有一张文风云脸已确认可用。
2. **字体库里没有集合**：至少需要含 **rc.4** 的构建，且包已启用 / 脸已确认；系统栈则看语种勾选是否仍开启。
3. **块侧栏没有「文派字库」面板**：请升到含 **2.0.0-rc.6** 的构建。多脸列表需要 **rc.7**。
4. **本站包装完仍是 `WF-*` / zip 名、对不上云字**：请升到 **2.0.0-rc.8** 后**重新安装**该 zip；已装旧包不会自动改目录。详见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)。
5. 字体库列表只有短码、没有「文风·…」：请升到含显示名修复的构建，并对该包重新安装 zip。

# 常见问题

> 适合谁看：页面字体没换、目录异常，或怀疑插件会不会切字时。

## 页面上字体没换

先分清你走的是哪条路：

**只用本站字体包**

1. 字体包已安装且为「使用中」吗？
2. 工具页（有本站包且文风云关时）里，该包的样式能否打开？前台样式地址是否 200？
3. 简单设置里，中文回退 / 正文 / 标题是否指向你启用的字？
4. 到 **外观 → 编辑器 → 样式 → 排版**，或块侧栏「文派字库」，确认选用的是包的 `font-family`（`wenfeng-*`）。显示名（如「文风·…」）只方便辨认，不能代替族名。

**走文风云**

1. 文风云是否已在设置里打开并保存？（默认关）
2. 是否有已确认的脸，或有效的字体名 / 项目名？
3. 到 **高级** / 工具检查 API Key（仅服务器校验；无效时按提示处理）。
4. 同样核对 `font-family` 是否为 `wenfeng-*`。

远程样式手工粘贴的对照，见[《网页字体引用与 CDN 接入》](https://docs.cocobook.com/books/windfonts/page/cdn)。

## 切片包里还是 WF-*，装完怎么变成 wenfeng-*？

属预期（**2.0.0-rc.8**）。安装时插件会把能识别的 `WF-*` / `windfonts-*` 对齐成 `wenfeng-{short}`，并把写入的 `local.css` 里的 `font-family` 改成同一短名；woff2 文件名不动。认不出时回退 zip 文件名。**已经装好的旧包不会自动改**；要得到新登记，请升到 rc.8 后重新拖入 zip。细节见[《文风字体包》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-packages)。

## 字体库里为什么是 wenfeng-xxxx，而不是「文风·某某体」？

`wenfeng-*` 是 **CSS 族名**（也常作包 id），排版和样式必须用它。  
给人看的名字约定是 **「文风·」+ 原名**（例如「文风·玄宗体」），出现在字体库 / 字体包页 / 工具卡片上。

若列表标题仍是短码：升级到含显示名修复的构建后，对该包重新安装 zip；旧登记不会自动改成「文风·…」。

选用时不要只抄显示名：到外观 → 编辑器 → 样式 → 排版，或块侧栏，确认实际写入的是 `wenfeng-*`。

## 侧栏改了字，为什么全站排版没变？

属预期。侧栏「文派字库」**只改当前块**。要进全站排版，请启用文风字体包或确认文风云脸，再到 **外观 → 编辑器 → 样式 → 排版**。见[《编辑器与全局样式》](https://docs.cocobook.com/books/wpfonts/page/wpfonts-editor)。

## 外观 → 样式里突然多了字体

属预期。自 **2.0.0-rc.5** 起，已启用的文风字体包、以及已确认可用的文风云字体脸，会自动写入用户全局样式，可在 **外观 → 编辑器 → 样式 → 排版** 看见。自 **rc.7** 起可同步**多张**云字脸。它们来自插件同步，不是主题被改过。

## 系统 · 某语种在字体库里不见了

到 **设置 → 文派字库 → 设置** 看四个勾选框（系统 · 中文 / 英文 / 日文 / 韩文）。默认全开；**取消勾选的语种不会登记进字体库**。重新勾选并保存即可。

## 停用包 / 去掉一张云字脸之后，排版里怎么还有字？

要区分两类东西：

- **插件同步写入的条目**：停用 / 删除包，或从已确认列表去掉某张脸后，插件会**只移除自己为该项写入的条目**。
- **你在站点编辑器里已经选中、落到块或样式上的值**：可能仍留在用户全局样式或块属性里，需要在编辑器里改回。

## 卸了插件，样式还在

全局样式归 WordPress（用户 `wp_global_styles`），**不是**主题文件。卸载插件会清设置与目录快照等插件数据，但**不会删除**用户全局样式。若排版还指着已卸掉的字体，请在站点编辑器里改回。

## 导出文件里有没有 API Key？导入为何整份拒绝？

自 **2.0.0-rc.7** 起，**设置 → 文派字库 → 工具** 可导出已启用包元数据与已确认云字脸。导出文件**不含** API Key。若你手头的文件里仍带有 Key（例如旧备份或手工拼的），导入会**整份拒绝**，不会半套写入。

## 公开样式 404 时会嵌入吗？

不会。公开样式返回非 CSS / 404 时，插件不嵌入该链接，也不宣称已加载。

## 目录是空的

本机还没有成功的 `catalog.json` 快照。可点「更新字体目录」，或先手填 `wenfeng-*`。打开设置页本身不会自动去拉文风。

## 更新失败，仍看见旧目录

这是预期行为：失败不会盖好快照。修好网络或稍后再点更新；冷却大约 60 秒。

## 设置里怎么找不到 API Key？

在 **简单** 视图且文风云关闭时，Key、区域、子集等故意不展示。打开文风云后，简单视图只多「选用字体」；其余在 **高级**。

## 工具页一上来就要填 Key？

自 **2.0.0-rc.11**：只要已安装本站字体包且文风云关闭，工具页会先给出 **本站字体包** 卡片。Key 检查与远程样式链接归在「这些项用于文风云」；不用云时不必先填 Key。

## 插件会切字吗？会改主题吗？

**不会切字，也不会写 theme.json / 主题文件。** 切分字体在文风完成。插件只消费文风云样式链接，或安装已切好的文风字体包，并把启用项同步进字体库与用户全局样式。装包时改写的是本站写出的 `local.css` 族名，不是源切片工程。

## 和手动贴文风样式链接是什么关系？

同一类远程嵌入。手动贴链接灵活；插件帮你管开关、服务器、多张已确认脸、字符范围和 Key 校验，少拼地址。项目白名单仍在文风控制台配置。