free-font 详细部署教程

1. 项目简介

free-font 是由开发者 jaywcjlove 维护的开源项目，旨在收集可商用的免费英文/汉字字体。该项目基于已不再维护的“字集”开源项目，新增了自动生成字体预览封面的脚本，并重新添加了大量中文字体以及一些开源英文字体，以方便《字帖宝宝》用户下载和使用。

核心特点：

商用免费字体集合：收录黑体、宋体、楷体、艺术体、手绘体、英文字体、开源字体等多种分类
自动预览生成：通过脚本自动为每个字体生成预览海报
网站自动生成：生成分类页面和字体列表页面
持续更新：社区驱动，定期收录新字体

重要说明：由于字体文件超过 1GB，且流量超出免费使用界限导致产生费用，项目已取消预览页面下方的字体预览功能。虽然这可能导致 GitHub 文件下载速度稍慢，但使用上不会受到影响。

2. 环境准备

2.1 系统要求

根据项目文档，部署需要以下环境：

组件	版本要求	说明
Node.js	推荐 18+	运行构建脚本
npm	随 Node.js 安装	包管理工具
Git	—	克隆仓库

2.2 安装前置依赖

安装 Node.js：

访问 Node.js 官网下载 LTS 版本，或使用包管理器安装：

# macOS
brew install node

# Ubuntu/Debian
sudo apt install nodejs npm

# Windows
# 从 https://nodejs.org/ 下载安装包

验证安装：

1 2	node -v npm -v

3. 本地部署

3.1 克隆仓库

1 2	git clone https://github.com/jaywcjlove/free-font.git cd free-font

3.2 安装依赖

1	npm install

该命令会安装项目所需的全部依赖，包括用于生成字体预览海报和 HTML 网站的脚本工具。

4. 构建与运行

4.1 生成字体预览海报

项目提供了两种生成预览海报的方式：

方式一：增量生成（推荐）

1	npm run one -- ./docs/fonts/english/Prima/Prima-Regular.otf

该命令会为指定字体生成预览海报，适合在添加新字体后使用。

方式二：生成所有字体预览

1	npm run all

该命令会生成所有字体的预览海报，并同时生成 HTML 网站。注意：由于字体数量较多，此操作可能需要较长时间。

4.2 生成 HTML 网站

开发模式（监听文件变化）：

1	npm run dev

该命令会启动监听模式，当模板文件发生变化时自动重新生成 HTML 网站。

生产模式（一次性生成）：

1	npm run start

该命令会生成完整的 HTML 网站。

4.3 预览网站

生成完成后，打开 docs/index.html 即可在浏览器中预览生成的字体展示网站。

5. 添加新字体

5.1 添加字体文件

将字体文件添加到 docs/fonts 目录中。如果是英文字体，放入 docs/fonts/english 目录即可自动分类。

5.2 配置字体信息

在 scripts/data.json 中添加字体相关信息。系统会自动生成部分字段（标注为“自动生成 - 不需要修改”），你需要配置的是：

{
  "name": "剔骨仿宋",
  "type": "艺术体",  // 字体分类：黑体、宋体、楷体、艺术体、手绘体、英文字体、开源字体
  "license": "商免",  // 许可协议："授权", "个人免费", "OFL-1.1", "IPA-1.0"
  "home": "https://zh.osdn.net/projects/jis2004/wiki/FrontPage",  // 官网/来源
  "officialDownload": true,  // 是否从官网下载
  "baidu": "1HLuBeaYlhtubLWcuJ_dxgQ?pwd=yfzk"  // 百度网盘提取码
}

字段说明：

字段	说明
`name`	字体名称（根据文件名自动生成）
`type`	字体分类，用于网站生成分类页面
`license`	许可协议类型
`home`	字体官网或来源地址
`officialDownload`	是否提供官网下载链接
`baidu`	百度网盘下载地址和提取码

5.3 重新生成网站

添加完成后，运行以下命令重新生成网站：

1	npm run start

6. 授权方式说明

在使用收录的字体前，需仔细阅读不同字体的授权条款：

授权类型	说明
免费商用字体	个人或厂商免费提供给商业机构使用，但非开源软件，不同厂商有不同限制，厂商有权收回权限
GPL-2.0	GNU 通用公共许可证，要求使用该字体的作品也以 GPL 许可分发（有争议，使用文泉系列字体需谨慎）
OFL-1.1	SIL 开放字体许可证，不会扩散到使用该字体的作品上，是开源字体的首选授权条款
IPA-1.0	日本 IPA 制定的开放字型授权条款，符合开源定义

7. 常见问题与解决方案

7.1 安装依赖失败

问题：npm install 报错。

解决方案：检查 Node.js 版本是否满足要求，尝试清除缓存后重试：

1 2	npm cache clean --force npm install

7.2 生成预览海报失败

问题：npm run one 或 npm run all 执行失败。

解决方案：确保字体文件路径正确，检查文件是否存在且格式受支持。

7.3 网站生成后无法访问

问题：docs/index.html 打开后空白或样式丢失。

解决方案：确保已运行 npm run start 生成完整的 HTML 网站，检查文件路径是否正确。

7.4 字体下载速度慢

原因：项目字体文件超过 1GB，GitHub 免费流量有限。

解决方案：这是正常现象，可尝试使用 GitHub 加速服务，或通过百度网盘链接下载（在 data.json 中配置）。

8. 部署架构总结

环节	工具/命令	说明
环境准备	Node.js 18+	运行构建脚本
依赖安装	`npm install`	安装项目依赖
生成预览	`npm run one` / `npm run all`	为字体生成预览海报
生成网站	`npm run start`	生成完整 HTML 网站
开发模式	`npm run dev`	监听变化自动重新生成
添加字体	编辑 `scripts/data.json`	配置字体分类和授权信息

free-font 本质上是一个字体资源集合与展示网站生成器。部署的核心工作是安装 Node.js 环境、克隆项目、安装依赖，然后通过 npm 脚本生成网站和预览海报。如果你需要添加新字体，只需将字体文件放入 docs/fonts 目录并在 scripts/data.json 中配置相关信息即可。部署完成后，你可以通过打开 docs/index.html 预览完整的字体展示网站。