根本原因是VSCode调试时cwd不固定且未继承字体环境，registerFont()必须用绝对路径并在canvas初始化后调用；需在launch.json中显式设cwd为${workspaceFolder}、配置env变量（如FONTCONFIG_PATH）、并在代码中用path.resolve(__dirname, ...)构造路径且先调用createCanvas()触发初始化。
Node-Canvas 在 VSCode 调试中报 FontConfig: Cannot load default config file 或 Failed to load font: /path/to/font.ttf，根本原因不是字体没下载，而是 canvas 模块在调试模式下无法正确解析相对路径或继承系统字体环境 —— 尤其当使用 registerFont() 时，路径必须是绝对路径，且不能依赖 process.cwd() 的运行时上下文。
为什么 registerFont('./fonts/SimHei.ttf') 在终端运行正常，但 VSCode 调试时失败？
VSCode 启动调试器时，默认工作目录（cwd）可能不是你预期的项目根目录；launch.json 中未显式指定 cwd，会导致 ./fonts/... 解析为 VSCode 安装目录或用户主目录下的子路径。更关键的是：Node-Canvas 的底层依赖（如 fontconfig on Linux/macOS、GDI on Windows）在调试会话中不自动继承 shell 的字体配置或 FONTCONFIG_PATH 环境变量。
-
registerFont()接收的必须是绝对路径，相对路径会被 canvas 忽略或静默失败 -
process.cwd()在调试中可能指向.vscode目录、用户 home 或空路径，不可靠 - Windows 下若用中文路径（如
C:项目 ontsSimHei.ttf），需确保路径字符串用双反斜杠\或正斜杠/，否则 Node 会误解析为转义字符
如何在 launch.json 中正确传递字体路径和环境变量？
必须显式设置 cwd 和 env，让 canvas 初始化时能定位字体文件并加载系统字体配置。以下配置适用于 macOS/Linux 和 Windows（路径需按实际调整）：
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "canvas-debug",
"program": "${workspaceFolder}/index.js",
"cwd": "${workspaceFolder}",
"env": {
"NODE_ENV": "development",
"FONTCONFIG_PATH": "/etc/fonts",
"GDK_PIXBUF_MODULE_FILE": "/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache"
},
"console": "integratedTerminal"
}
]
}
-
cwd强制设为${workspaceFolder}，确保__dirname和path.resolve()行为一致 - macOS 用户可省略
FONTCONFIG_PATH，但需确认/opt/homebrew/etc/fonts/fonts.conf存在（Homebrew 安装 fontconfig 后） - Windows 用户无需
FONTCONFIG_PATH，但必须在env中添加"FONT_DIR": "C:/Windows/Fonts"（注意正斜杠或双反斜杠） -
GDK_PIXBUF_MODULE_FILE是 Linux 下图像解码必需项，缺失会导致 PNG 输出异常
registerFont() 的调用时机和路径构造必须严格满足条件
不能在模块顶层直接写 registerFont('./fonts/xxx.ttf') —— 此时 __dirname 可能指向 node_modules/canvas 内部路径。必须在应用逻辑入口（如 index.js 最顶部）用 path.resolve() 构造绝对路径，并确保 canvas 已初始化：
const { createCanvas, loadImage } = require('canvas');
const path = require('path');
// ✅ 正确：绝对路径 + 显式 resolve
const fontPath = path.resolve(__dirname, 'fonts', 'SimHei.ttf');
createCanvas(1, 1); // 触发 canvas 初始化（必要！）
require('canvas').registerFont(fontPath, { family: 'SimHei' });
// ❌ 错误：相对路径、未初始化就注册、或放在异步回调里
// registerFont('./fonts/SimHei.ttf', { family: 'SimHei' }); // 会静默失败
- 必须先调用任意 canvas API（如
createCanvas()或loadImage()）触发底层初始化，再注册字体 -
path.resolve(__dirname, ...)比__dirname + '/fonts/...'更安全，避免多层../导致路径越界 - 注册后需重启调试会话，canvas 不支持热重载字体
验证字体是否真正生效的唯一可靠方式
不要只看控制台有没有报错 —— registerFont() 即使失败也不会 throw，只会静默忽略。真正验证方法是生成一张含文字的图，然后检查输出是否渲染出预期字体：
const { createCanvas } = require('canvas');
const fs = require('fs');
const canvas = createCanvas(200, 100);
const ctx = canvas.getContext('2d');
ctx.font = '24px SimHei'; // 必须与 registerFont 的 family 完全一致
ctx.fillText('测试中文', 10, 50);
fs.writeFileSync('test.png', canvas.toBuffer('image/png'));
- 如果输出图片中文字显示为方框或默认无衬线体，说明字体未注册成功
- Linux/macOS 下可用
fc-list | grep SimHei确认系统级字体已安装 - Windows 下检查
C:WindowsFonts是否存在该字体文件，且文件权限允许读取
最易被忽略的点：Node-Canvas 的字体注册是进程级单例，一旦初始化失败，后续所有 registerFont() 调用都无效 —— 所以首次调试务必清空 node_modules 并重装 canvas（npm rebuild canvas），尤其当你从非调试模式切到调试模式时，底层 native binding 可能缓存了错误状态。
