尧图网页设计 
1. 从一次验证码白屏说起imagettftext 报 Could not find/open font 到底卡在哪你写了一段 PHP 验证码脚本本地跑得好好的换台机器或者换个目录页面直接变成一行 Warningimagettftext(): Could not find/open font。更气人的是有时候它不报错只是画布上一片空白中文一个字都不显示。这个报错的核心含义其实很直白PHP 的 GD 扩展拿着你给的字体路径去找.ttf文件没找到或者找到了但没权限读。imagettftext是 GD 库里专门用来把 TrueType 字体渲染到图像上的函数中文验证码、水印、海报文字都靠它。它和imagestring最大的区别是imagestring用内置点阵字体只能画 ASCIIimagettftext必须外挂一个字体文件所以字体路径就成了整个链路里最脆弱的一环。适合谁看正在用 PHP 做中文验证码、图形水印、后台导出带字图片的开发者尤其是从教程复制代码后直接踩坑的新手。这个报错通常不是单一原因而是三个层面叠在一起第一层是字体文件真实路径不对相对路径的基准目录和你以为的不一样第二层是中文编码没走 mbstring字符串本身是乱码GD 拿到乱码自然画不出东西第三层是 GD 扩展的字体索引和权限问题文件明明在PHP 进程却读不到。我试过把这三点分开排查比一股脑改路径高效得多。下面按「先定位、再配置、后验证」的顺序拆开讲每一步都给可复制的代码。需要先说明一点本文所有请求端点示例都指向 TaoToken 的兼容接口它提供 OpenAI 兼容的 API 形态方便你在同一套代码里切换模型做验证码识别或文本生成。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。后面第五节会给出把请求端点改过去后复测同一张验证码的完整做法。2. 排查字体路径前先把 TaoToken 的接入信息备好很多人一看到Could not find/open font就只盯着字体文件其实在动手改路径之前先把「请求端点」这条线理清楚能让后面的复测省很多事。因为验证码场景经常伴随一个需求把生成的验证码图片交给模型做 OCR 识别或者用模型生成干扰文本。这时候你需要一个稳定的 API 端点TaoToken 就是干这个的。TaoToken 是什么它是一个大模型 API 聚合网关对外暴露 OpenAI 兼容的/v1/chat/completions等接口。你能用它做什么把验证码识别、文本润色、代码补全这类请求统一发到一个 Base URL换模型只改 Model ID不用改代码结构。适合谁正在做 PHP 后端、需要调用模型能力但不想为每个厂商维护一套 SDK 的开发者。接入前你需要准备三样东西我把它叫「三件套」后面配置片段里会反复出现项目说明示例值Base URL请求根地址不带具体路径https://taotoken.net/apiAPI Key控制台生成的密钥sk-xxxxxxxxModel ID具体模型标识按控制台可用列表填写API Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后复制保存页面刷新后不再完整显示。如果你只是想先验证模型通不通可以用模型对话页面直接发一条消息测试地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这里要强调一个容易混的点字体路径问题和 API 端点问题是两条独立的线。字体路径错了imagettftext直接报 Warning跟 API 一点关系没有API 端点错了是请求返回 401 或连接失败。之所以放在一起讲是因为验证码项目里两者经常同时出现分开排查才不会互相干扰。先把三件套记下来第三节我们回到字体路径本身。3. 可复制的字体绝对路径配置与最小验证脚本这一节是全文的核心直接给能跑的代码。先解决路径再解决编码最后给一个最小验证脚本。3.1 字体路径相对路径是万恶之源原始代码里写的是$fontfile./ttf/simhei.ttf;。这个./的基准目录不是脚本所在目录而是 PHP 进程的当前工作目录CWD。在 CLI 下 CWD 通常是你执行命令的目录在 FPM 下可能是 Web 服务器的工作目录两者经常不一致所以同一份代码换个入口就报错。最稳的做法是用绝对路径。有两种写法任选其一?php // 写法一直接写死绝对路径适合路径固定的生产环境 $fontfile D:/phpstudy_pro/WWW/cheshi/ttf/simhei.ttf; // 写法二基于 __DIR__ 动态拼接推荐迁移目录不用改代码 $fontfile __DIR__ . /ttf/simhei.ttf; // 无论哪种写法都建议再用 realpath 校验一次 $fontfile realpath($fontfile); if ($fontfile false) { exit(字体文件不存在请检查路径 . $fontfile); }注意 Windows 下路径分隔符用正斜杠/或双反斜杠\\单反斜杠\在 PHP 字符串里是转义符D:\phpstudy_pro\...里的\p、\t会被当成转义序列这是很多人路径明明对却读不到的隐藏原因。realpath()会把相对路径转成绝对路径并在文件不存在时返回false用它做一次兜底判断比让 GD 抛 Warning 友好得多。3.2 中文编码mbstring 没开字就是乱码imagettftext本身能画 UTF-8 中文但前提是你的字符串真的是 UTF-8。原始代码用mb_substr从中文集合里取字这依赖mbstring扩展。如果php.ini里extensionmbstring被注释掉mb_strlen和mb_substr会报未定义函数或者退化成按字节截取把三字节的汉字切成半个GD 拿到残缺字节自然画不出。检查方法很简单在脚本顶部加一行?php var_dump(extension_loaded(mbstring)); // 输出 bool(true) 才算正常如果输出false去php.ini打开extensionmbstring重启 PHP 服务。另外确认脚本文件本身保存为 UTF-8 无 BOM 编码BOM 头会作为输出提前发送导致header(content-type:image/gif)失效图片显示成乱码。3.3 最小验证脚本先确认字体能画出来在排查验证码之前先用一个最小脚本确认imagettftext本身工作正常。把下面这段存成font_test.php只画两个字?php error_reporting(E_ALL); ini_set(display_errors, 1); $fontfile realpath(__DIR__ . /ttf/simhei.ttf); if ($fontfile false) { exit(字体路径无效); } $img imagecreate(200, 80); imagecolorallocate($img, 255, 255, 255); // 背景白 $color imagecolorallocate($img, 0, 0, 0); // 文字黑 $text 测试; $size 30; $angle 0; $info imagettfbbox($size, $angle, $fontfile, $text); $w $info[4] - $info[6]; $h $info[1] - $info[7]; $x (imagesx($img) - $w) / 2; $y (imagesy($img) $h) / 2; imagettftext($img, $size, $angle, $x, $y, $color, $fontfile, $text); header(Content-Type: image/png); imagepng($img); imagedestroy($img);浏览器访问这个文件能看到「测试」两个字说明字体路径、mbstring、GD 三件套都正常。看不到字但没报错多半是字体文件损坏或不是 TrueType 格式报Could not find/open font回到 3.1 检查路径和权限。3.4 把请求端点配置成可复制的 JSON 片段验证码项目里如果还要调模型建议把接入信息写成配置文件避免硬编码。下面是一个config.json示例路径放在项目根目录{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model_id: 按控制台可用列表填写, font_file: ./ttf/simhei.ttf }PHP 里读取?php $cfg json_decode(file_get_contents(__DIR__ . /config.json), true); $fontfile realpath(__DIR__ . / . ltrim($cfg[font_file], ./));这样字体路径和 API 端点都在一个文件里管理迁移环境只改config.json。如果你用的是 Claude Code 这类编码工具做长期开发可以把 Base URL、Key、Model ID 三件套填进它的配置走 Coding Plan 更省事地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。4. 验证请求从字体渲染到接口复测的完整链路配置改完必须验证不然你不知道是路径生效了还是缓存骗了你。这一节分两步先验证字体渲染再验证 API 请求。4.1 验证字体渲染结果用 3.3 的最小脚本确认能出图后把原始验证码脚本的字体路径也改成绝对路径重新访问。如果还是空白用imagettfbbox打印边界值?php $info imagettfbbox(20, 0, $fontfile, 中文); var_dump($info);正常会返回 8 个数字的数组比如[0, 8, 0, -8, 40, 8, 40, -8]这种结构。如果返回false说明字体文件 GD 读不了换一个确认可用的simhei.ttf或msyh.ttf再试。imagettfbbox返回false是比imagettftext更早暴露问题的信号建议在正式画字之前先调它。4.2 验证 API 请求是否通字体搞定后用一段 PHP 代码测试 TaoToken 端点。这里用 cURL 发一个最小请求?php $ch curl_init(https://taotoken.net/api/v1/chat/completions); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER true, CURLOPT_POST true, CURLOPT_HTTPHEADER [ Content-Type: application/json, Authorization: Bearer sk-你的密钥, ], CURLOPT_POSTFIELDS json_encode([ model 按控制台可用列表填写, messages [ [role user, content 回复两个字收到], ], ]), ]); $resp curl_exec($ch); $code curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo HTTP: $code\n; echo $resp;返回HTTP: 200且 body 里有choices数组说明端点、Key、Model ID 三件套都对。如果返回 401是 Key 问题返回 404检查 Base URL 有没有多写或少写/v1连接超时检查网络出口。这一步和字体路径无关但验证码项目里经常需要把图片转 base64 发给模型识别所以端点必须先通。4.3 把验证码图片交给模型复测一个实用场景生成验证码后把图片 base64 编码发给支持视觉的模型做识别验证你的验证码是否「人眼可读、机器难读」。PHP 里这样拼?php $imgData base64_encode(file_get_contents(captcha.png)); $payload [ model 按控制台可用列表填写, messages [[ role user, content [ [type text, text 识别图中的中文字符], [type image_url, image_url [ url data:image/png;base64, . $imgData, ]], ], ]], ];把这段 payload POST 到https://taotoken.net/api/v1/chat/completions如果模型能返回你画的那几个字说明整条链路——字体渲染、编码、接口——全部打通。这一步也是复测「改到 TaoToken 后同一验证码输出是否正常」的最直接方式。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth排查时最怕报错信息看不懂这里把几个高频错误和对应根因列清楚对照着改。Warning: imagettftext(): Could not find/open font这是本文主角。九成是路径问题相对路径基准不对、Windows 单反斜杠被转义、文件权限不足。按 3.1 改成realpath(__DIR__ . /ttf/simhei.ttf)基本能解决。如果realpath返回false用file_exists和is_readable分别确认文件存在且可读。HTTP 401 UnauthorizedAPI Key 错误或没带。检查Authorization: Bearer sk-xxx头有没有拼错Key 是否被截断是否用了已删除的 Key。去控制台重新生成一个再试地址 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。local proxy failed / connection refused本地网络出口问题不是 TaoToken 服务端问题。检查本机是否能正常访问外网cURL 是否走了系统代理但代理没开。PHP 里可以临时关掉代理环境变量再测。Cannot read properties of undefined (reading choices)这是前端或调用方解析响应时的错误说明返回的 JSON 里没有choices字段。常见原因是请求根本没成功返回的是错误对象或者你把 Base URL 写成了https://taotoken.net/api却没拼/v1/chat/completions。先打印原始响应体别急着取choices。OAuth / 认证失败如果你用的是 Claude Code 或 Codex 这类工具认证方式可能不是简单 Bearer。Claude Code 走 Anthropic 兼容端点配置时 Base URL 填https://taotoken.net/apiKey 填控制台生成的密钥Model ID 按可用列表填。Codex 的auth.json里同样要写全三件套缺一个都会认证失败。相关文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。字体能画英文画不出中文mbstring 没开或者字符串不是 UTF-8。用mb_check_encoding($text, UTF-8)确认返回false就说明编码有问题。另外确认字体文件本身包含中文字形有些精简版 ttf 只有拉丁字符。图片输出乱码或提示 headers already sent脚本文件有 BOM 头或者?php之前有空格/空行。用编辑器切到十六进制模式看开头是不是EF BB BF是的话另存为无 BOM 的 UTF-8。排查顺序建议固定成先跑 3.3 最小脚本确认字体 → 再跑 4.2 确认 API → 最后合起来跑验证码。这样任何一步出错都能立刻定位不会在两条线之间来回猜。6. 把字体路径和请求端点都收进配置下次直接复用走到这里Could not find/open font的根因基本就三类路径、编码、权限。我的习惯是把字体路径、API 三件套全部收进一个config.json代码里只读配置不写死。这样换机器、换目录、换模型都只改一个文件。如果你还在用 Claude Code 做长期编码把 Base URL、Key、Model ID 填进它的配置后可以让它帮你批量检查项目里所有imagettftext调用的字体路径是否都用了realpath。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。需要长期跑 Agent 或编码任务的Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个实用技巧在项目里加一个check_env.php一次性输出 mbstring 是否开启、GD 版本、字体文件realpath结果、API 连通性。部署到新环境先访问它比逐个脚本试错快得多。字体路径这件事本质就是「让 PHP 拿到一个它一定能读到的绝对路径」剩下的都是编码和权限的细节。 imagettftext 生成中文验证码报 Could not find/open font？把字体路径改到 TaoToken 前先排查这几处
1. 从一次验证码白屏说起imagettftext 报 Could not find/open font 到底卡在哪你写了一段 PHP 验证码脚本本地跑得好好的换台机器或者换个目录页面直接变成一行 Warningimagettftext(): Could not find/open font。更气人的是有时候它不报错只是画布上一片空白中文一个字都不显示。这个报错的核心含义其实很直白PHP 的 GD 扩展拿着你给的字体路径去找.ttf文件没找到或者找到了但没权限读。imagettftext是 GD 库里专门用来把 TrueType 字体渲染到图像上的函数中文验证码、水印、海报文字都靠它。它和imagestring最大的区别是imagestring用内置点阵字体只能画 ASCIIimagettftext必须外挂一个字体文件所以字体路径就成了整个链路里最脆弱的一环。适合谁看正在用 PHP 做中文验证码、图形水印、后台导出带字图片的开发者尤其是从教程复制代码后直接踩坑的新手。这个报错通常不是单一原因而是三个层面叠在一起第一层是字体文件真实路径不对相对路径的基准目录和你以为的不一样第二层是中文编码没走 mbstring字符串本身是乱码GD 拿到乱码自然画不出东西第三层是 GD 扩展的字体索引和权限问题文件明明在PHP 进程却读不到。我试过把这三点分开排查比一股脑改路径高效得多。下面按「先定位、再配置、后验证」的顺序拆开讲每一步都给可复制的代码。需要先说明一点本文所有请求端点示例都指向 TaoToken 的兼容接口它提供 OpenAI 兼容的 API 形态方便你在同一套代码里切换模型做验证码识别或文本生成。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。后面第五节会给出把请求端点改过去后复测同一张验证码的完整做法。2. 排查字体路径前先把 TaoToken 的接入信息备好很多人一看到Could not find/open font就只盯着字体文件其实在动手改路径之前先把「请求端点」这条线理清楚能让后面的复测省很多事。因为验证码场景经常伴随一个需求把生成的验证码图片交给模型做 OCR 识别或者用模型生成干扰文本。这时候你需要一个稳定的 API 端点TaoToken 就是干这个的。TaoToken 是什么它是一个大模型 API 聚合网关对外暴露 OpenAI 兼容的/v1/chat/completions等接口。你能用它做什么把验证码识别、文本润色、代码补全这类请求统一发到一个 Base URL换模型只改 Model ID不用改代码结构。适合谁正在做 PHP 后端、需要调用模型能力但不想为每个厂商维护一套 SDK 的开发者。接入前你需要准备三样东西我把它叫「三件套」后面配置片段里会反复出现项目说明示例值Base URL请求根地址不带具体路径https://taotoken.net/apiAPI Key控制台生成的密钥sk-xxxxxxxxModel ID具体模型标识按控制台可用列表填写API Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后复制保存页面刷新后不再完整显示。如果你只是想先验证模型通不通可以用模型对话页面直接发一条消息测试地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这里要强调一个容易混的点字体路径问题和 API 端点问题是两条独立的线。字体路径错了imagettftext直接报 Warning跟 API 一点关系没有API 端点错了是请求返回 401 或连接失败。之所以放在一起讲是因为验证码项目里两者经常同时出现分开排查才不会互相干扰。先把三件套记下来第三节我们回到字体路径本身。3. 可复制的字体绝对路径配置与最小验证脚本这一节是全文的核心直接给能跑的代码。先解决路径再解决编码最后给一个最小验证脚本。3.1 字体路径相对路径是万恶之源原始代码里写的是$fontfile./ttf/simhei.ttf;。这个./的基准目录不是脚本所在目录而是 PHP 进程的当前工作目录CWD。在 CLI 下 CWD 通常是你执行命令的目录在 FPM 下可能是 Web 服务器的工作目录两者经常不一致所以同一份代码换个入口就报错。最稳的做法是用绝对路径。有两种写法任选其一?php // 写法一直接写死绝对路径适合路径固定的生产环境 $fontfile D:/phpstudy_pro/WWW/cheshi/ttf/simhei.ttf; // 写法二基于 __DIR__ 动态拼接推荐迁移目录不用改代码 $fontfile __DIR__ . /ttf/simhei.ttf; // 无论哪种写法都建议再用 realpath 校验一次 $fontfile realpath($fontfile); if ($fontfile false) { exit(字体文件不存在请检查路径 . $fontfile); }注意 Windows 下路径分隔符用正斜杠/或双反斜杠\\单反斜杠\在 PHP 字符串里是转义符D:\phpstudy_pro\...里的\p、\t会被当成转义序列这是很多人路径明明对却读不到的隐藏原因。realpath()会把相对路径转成绝对路径并在文件不存在时返回false用它做一次兜底判断比让 GD 抛 Warning 友好得多。3.2 中文编码mbstring 没开字就是乱码imagettftext本身能画 UTF-8 中文但前提是你的字符串真的是 UTF-8。原始代码用mb_substr从中文集合里取字这依赖mbstring扩展。如果php.ini里extensionmbstring被注释掉mb_strlen和mb_substr会报未定义函数或者退化成按字节截取把三字节的汉字切成半个GD 拿到残缺字节自然画不出。检查方法很简单在脚本顶部加一行?php var_dump(extension_loaded(mbstring)); // 输出 bool(true) 才算正常如果输出false去php.ini打开extensionmbstring重启 PHP 服务。另外确认脚本文件本身保存为 UTF-8 无 BOM 编码BOM 头会作为输出提前发送导致header(content-type:image/gif)失效图片显示成乱码。3.3 最小验证脚本先确认字体能画出来在排查验证码之前先用一个最小脚本确认imagettftext本身工作正常。把下面这段存成font_test.php只画两个字?php error_reporting(E_ALL); ini_set(display_errors, 1); $fontfile realpath(__DIR__ . /ttf/simhei.ttf); if ($fontfile false) { exit(字体路径无效); } $img imagecreate(200, 80); imagecolorallocate($img, 255, 255, 255); // 背景白 $color imagecolorallocate($img, 0, 0, 0); // 文字黑 $text 测试; $size 30; $angle 0; $info imagettfbbox($size, $angle, $fontfile, $text); $w $info[4] - $info[6]; $h $info[1] - $info[7]; $x (imagesx($img) - $w) / 2; $y (imagesy($img) $h) / 2; imagettftext($img, $size, $angle, $x, $y, $color, $fontfile, $text); header(Content-Type: image/png); imagepng($img); imagedestroy($img);浏览器访问这个文件能看到「测试」两个字说明字体路径、mbstring、GD 三件套都正常。看不到字但没报错多半是字体文件损坏或不是 TrueType 格式报Could not find/open font回到 3.1 检查路径和权限。3.4 把请求端点配置成可复制的 JSON 片段验证码项目里如果还要调模型建议把接入信息写成配置文件避免硬编码。下面是一个config.json示例路径放在项目根目录{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model_id: 按控制台可用列表填写, font_file: ./ttf/simhei.ttf }PHP 里读取?php $cfg json_decode(file_get_contents(__DIR__ . /config.json), true); $fontfile realpath(__DIR__ . / . ltrim($cfg[font_file], ./));这样字体路径和 API 端点都在一个文件里管理迁移环境只改config.json。如果你用的是 Claude Code 这类编码工具做长期开发可以把 Base URL、Key、Model ID 三件套填进它的配置走 Coding Plan 更省事地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。4. 验证请求从字体渲染到接口复测的完整链路配置改完必须验证不然你不知道是路径生效了还是缓存骗了你。这一节分两步先验证字体渲染再验证 API 请求。4.1 验证字体渲染结果用 3.3 的最小脚本确认能出图后把原始验证码脚本的字体路径也改成绝对路径重新访问。如果还是空白用imagettfbbox打印边界值?php $info imagettfbbox(20, 0, $fontfile, 中文); var_dump($info);正常会返回 8 个数字的数组比如[0, 8, 0, -8, 40, 8, 40, -8]这种结构。如果返回false说明字体文件 GD 读不了换一个确认可用的simhei.ttf或msyh.ttf再试。imagettfbbox返回false是比imagettftext更早暴露问题的信号建议在正式画字之前先调它。4.2 验证 API 请求是否通字体搞定后用一段 PHP 代码测试 TaoToken 端点。这里用 cURL 发一个最小请求?php $ch curl_init(https://taotoken.net/api/v1/chat/completions); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER true, CURLOPT_POST true, CURLOPT_HTTPHEADER [ Content-Type: application/json, Authorization: Bearer sk-你的密钥, ], CURLOPT_POSTFIELDS json_encode([ model 按控制台可用列表填写, messages [ [role user, content 回复两个字收到], ], ]), ]); $resp curl_exec($ch); $code curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo HTTP: $code\n; echo $resp;返回HTTP: 200且 body 里有choices数组说明端点、Key、Model ID 三件套都对。如果返回 401是 Key 问题返回 404检查 Base URL 有没有多写或少写/v1连接超时检查网络出口。这一步和字体路径无关但验证码项目里经常需要把图片转 base64 发给模型识别所以端点必须先通。4.3 把验证码图片交给模型复测一个实用场景生成验证码后把图片 base64 编码发给支持视觉的模型做识别验证你的验证码是否「人眼可读、机器难读」。PHP 里这样拼?php $imgData base64_encode(file_get_contents(captcha.png)); $payload [ model 按控制台可用列表填写, messages [[ role user, content [ [type text, text 识别图中的中文字符], [type image_url, image_url [ url data:image/png;base64, . $imgData, ]], ], ]], ];把这段 payload POST 到https://taotoken.net/api/v1/chat/completions如果模型能返回你画的那几个字说明整条链路——字体渲染、编码、接口——全部打通。这一步也是复测「改到 TaoToken 后同一验证码输出是否正常」的最直接方式。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth排查时最怕报错信息看不懂这里把几个高频错误和对应根因列清楚对照着改。Warning: imagettftext(): Could not find/open font这是本文主角。九成是路径问题相对路径基准不对、Windows 单反斜杠被转义、文件权限不足。按 3.1 改成realpath(__DIR__ . /ttf/simhei.ttf)基本能解决。如果realpath返回false用file_exists和is_readable分别确认文件存在且可读。HTTP 401 UnauthorizedAPI Key 错误或没带。检查Authorization: Bearer sk-xxx头有没有拼错Key 是否被截断是否用了已删除的 Key。去控制台重新生成一个再试地址 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。local proxy failed / connection refused本地网络出口问题不是 TaoToken 服务端问题。检查本机是否能正常访问外网cURL 是否走了系统代理但代理没开。PHP 里可以临时关掉代理环境变量再测。Cannot read properties of undefined (reading choices)这是前端或调用方解析响应时的错误说明返回的 JSON 里没有choices字段。常见原因是请求根本没成功返回的是错误对象或者你把 Base URL 写成了https://taotoken.net/api却没拼/v1/chat/completions。先打印原始响应体别急着取choices。OAuth / 认证失败如果你用的是 Claude Code 或 Codex 这类工具认证方式可能不是简单 Bearer。Claude Code 走 Anthropic 兼容端点配置时 Base URL 填https://taotoken.net/apiKey 填控制台生成的密钥Model ID 按可用列表填。Codex 的auth.json里同样要写全三件套缺一个都会认证失败。相关文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。字体能画英文画不出中文mbstring 没开或者字符串不是 UTF-8。用mb_check_encoding($text, UTF-8)确认返回false就说明编码有问题。另外确认字体文件本身包含中文字形有些精简版 ttf 只有拉丁字符。图片输出乱码或提示 headers already sent脚本文件有 BOM 头或者?php之前有空格/空行。用编辑器切到十六进制模式看开头是不是EF BB BF是的话另存为无 BOM 的 UTF-8。排查顺序建议固定成先跑 3.3 最小脚本确认字体 → 再跑 4.2 确认 API → 最后合起来跑验证码。这样任何一步出错都能立刻定位不会在两条线之间来回猜。6. 把字体路径和请求端点都收进配置下次直接复用走到这里Could not find/open font的根因基本就三类路径、编码、权限。我的习惯是把字体路径、API 三件套全部收进一个config.json代码里只读配置不写死。这样换机器、换目录、换模型都只改一个文件。如果你还在用 Claude Code 做长期编码把 Base URL、Key、Model ID 填进它的配置后可以让它帮你批量检查项目里所有imagettftext调用的字体路径是否都用了realpath。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。需要长期跑 Agent 或编码任务的Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个实用技巧在项目里加一个check_env.php一次性输出 mbstring 是否开启、GD 版本、字体文件realpath结果、API 连通性。部署到新环境先访问它比逐个脚本试错快得多。字体路径这件事本质就是「让 PHP 拿到一个它一定能读到的绝对路径」剩下的都是编码和权限的细节。