node-canvas自定义字体不生效：如何确认正确字体家族名？

提取TTF字体正确家族名的可靠方法 #

1. 命令行工具（Linux/macOS） #

使用fc-list工具直接查询字体文件的元数据：

fc-list file:///绝对路径/to/your/font.ttf

输出结果中会包含字体的官方家族名（family字段），这是node-canvas能识别的正确名称。

2. 系统字体查看工具 #

• Windows：直接双击打开TTF文件，窗口顶部显示的字体名称即为家族名。
• macOS：用Font Book打开字体，查看「信息」面板中的「家族」字段。
• 第三方工具：使用FontForge打开字体，在「字体信息」面板中获取准确的家族名。

3. Node.js脚本读取元数据 #

借助opentype.js库直接解析TTF文件：

1. 先安装依赖：

npm install opentype.js

2. 编写解析脚本：

const opentype = require('opentype.js');
const path = require('path');
const fontPath = path.join(__dirname, 'font.ttf');

opentype.load(fontPath, (err, font) => {
  if (err) {
    console.error('加载字体失败:', err);
    return;
  }
  console.log('字体家族名:', font.names.fontFamily.en);
  console.log('字体子家族名:', font.names.fontSubfamily.en);
});

运行脚本后就能得到字体定义的官方家族名，这是最准确的方式。

调试与验证技巧 #

1. 检查字体是否成功注册 #

注册字体后，用getFonts()方法列出所有已加载的字体，确认自定义字体是否在列，以及显示的家族名：

const { createCanvas, registerFont } = require('canvas');
const path = require('path');
const fontPath = path.join(__dirname, 'font.ttf');
registerFont(fontPath, { family: 'CustomFont' });

// 打印已注册字体列表
console.log('已注册字体:', createCanvas().getFonts());

如果列表中没有目标字体，说明路径错误或字体文件损坏；如果存在，核对显示的家族名是否与你设置的一致。

2. 简化测试代码 #

暂时移除 fallback 字体，直接使用自定义字体测试：

ctx.font = '30px "CustomFont"';

如果文本无法渲染，说明字体未正确加载；如果渲染成系统默认字体，大概率是家族名不匹配。

3. 验证字体文件路径 #

用fs模块检查路径是否正确，避免因路径错误导致字体未加载：

const fs = require('fs');
console.log('字体文件存在:', fs.existsSync(fontPath));

4. 排除字体文件问题 #

换一个确认可用的TTF字体（比如系统自带的字体文件拷贝一份）测试，排除字体本身损坏或不兼容的情况。

代码修正示例 #

假设通过上述方法获取到正确的字体家族名为MyOfficialFont，修正后的代码如下：

const { createCanvas, registerFont } = require('canvas');
const path = require('path');

const fontPath = path.join(__dirname, 'font.ttf');
// 使用正确的家族名注册
registerFont(fontPath, { family: 'MyOfficialFont' });

const canvas = createCanvas(800, 600);
const ctx = canvas.getContext('2d');
// 字体声明与注册的家族名保持一致
ctx.font = '30px "MyOfficialFont", sans-serif';
ctx.fillStyle = 'black';
ctx.fillText('Hello World', 50, 50);

内容的提问来源于stack exchange，提问作者chenzen