故障排查

工具调用返回错误

  • 确认jsonrpc:"2.0"字段必须存在
  • 确认工具名在24个注册名中
  • 参数Schema:必填字段是否缺失/类型是否正确
  • wrangler tail查看实时错误日志

PNG渲染失败或图片空白

  • 确认@resvg/resvg-wasm已正确安装(npm install无误)
  • CJK文字不显示→确认字体文件已上传到Cloudflare KV
  • 图片完全空白→检查表达式语法(sin(x)非sin x，x^2非x**2，log(x)非ln(x))
  • 数学符号不显示→使用pi而非π，函数必须用括号包裹参数

短链接失效或无法打开

  • 30天TTL过期是正常行为——短链接设计为临时性的
  • 使用/plot或/png端点直接渲染，将完整参数保留在URL中用于长期引用
  • 确认Token是完整的8个字符(字母+数字)

部署后Worker不工作

  • 确认npx wrangler login已完成Cloudflare账号OAuth认证
  • 确认wrangler.toml中kv_namespaces的id与Cloudflare Dashboard中创建的KV命名空间ID完全一致
  • KV绑定错误→在Dashboard的Workers & Pages→KV中检查命名空间是否存在

性能优化建议

  • 使用plot_png_link获取PNG图片URL而非plot_json中的base64数据(URL比base64小约100倍)
  • 批量渲染使用plot_multi_images(一次请求最多8个任务，复用WASM实例和字体缓存)
  • SVG渲染比PNG快约3倍——如果图表不含CJK文字优先选择SVG格式
  • 默认采样点数1000对绝大多数场景已足够，调高到5000对视觉改善微乎其微但渲染时间成倍增加
  • 分享图表使用短链接(/s/{token})而非一长串参数URL

CJK字体相关问题

  • 本地开发需要手动下载.ttf字体文件(如从Google Fonts下载Noto Sans SC)
  • 生产环境字体存储于Cloudflare KV，通过opentype.js按需将字形转换为SVG路径
  • 如果没有字体文件：英文和数字正常渲染，中文/日文/韩文显示为方块或空白

表达式解析常见错误

  • expr-eval不支持Python语法——x**2应为x^2，ln(x)应为log(x)
  • 三角函数必须用括号：sin(x)而非sin x
  • 隐式乘法不支持：2x应写成2*x
  • 常数使用英文字母：pi而非π，e而非自然常数符号

关于双版本号

package.json:0.2.0(npm发布版本)。SERVER_VERSION:0.4.14(constants.ts，health工具和initialize响应中报告)。两者不一致是故意设计——分别追踪npm包发布周期和Worker部署迭代次数。不要尝试对齐它们。