imgx-template-generator

IMGX Template Generator Skill

技能描述

生成符合 Satori 渲染约束的 IMGX Vue 模板，将文本转换为精美的卡片图片。

---

🚀 快速开始（三步流程）

第一步：理解架构（必读 3 分钟）

在开始之前，必须阅读以下文档：

为什么必须先读？

• 避免浪费时间创建不被使用的文件
• 理解 Satori 的严格限制（不是完整浏览器引擎）
• 掌握 Props 数据流，避免 Vue 警告

---

第二步：选择蓝图（按需求选择）

根据用户需求，选择对应的模板蓝图：

⚠️ 图标使用限制（重要）

IMGX 系统仅支持本地图标库（assets/icons/ 目录），不支持远程图标库：

当前可用图标集：

• twemoji: 68 个表情图标
  • 示例: twemoji:beaming-face-with-smiling-eyes 😁, twemoji:cowboy-hat-face 🤠
  • 位置: assets/icons/twemoji-face-icons.json

如何添加新图标集：

1. 将 Iconify JSON 格式的图标集放入 assets/icons/
2. 在 lib/icons.ts 中导入并注册新图标集
3. 使用格式: <prefix>:icon-name（prefix 为图标集的 prefix 字段）

查看可用图标： 查看 assets/icons/ 目录下的 .json 文件

---

✨ 每个蓝图包含：

• ✅ 适用场景说明
• ✅ 完整模板代码（可直接使用）
• ✅ Preset 配置示例
• ✅ 样式变体（2-4 种）
• ✅ 常见陷阱提示
• ✅ 测试 URL 示例
• ✅ 质量检查清单

---

第三步：执行工作流（3 个文件）

3.1 创建模板文件

// server/templates/[Name].ts
export const [Name]Template = `<div class="w-full h-full flex">
  <!-- 根据蓝图填充内容 -->
</div>`

要点：

• 文件名：PascalCase（MyTemplate.ts）
• 导出常量：[Name]Template
• 根元素必须：w-full h-full flex
• 所有元素必须：class="flex"

3.2 注册模板

// server/utils/image.ts
import { [Name]Template } from '../templates/[Name]'

const templateStrings: Record<string, string> = {
  // ... 其他模板
  '[Name]': [Name]Template,  // ← 新增这行
}

3.3 创建 Preset

# 1. 检查下一个可用编号
ls presets/*.json | sort

# 2. 创建 preset 文件
# presets/[code].json

**📋 Preset 命名规范**：参考 [preset-naming-convention.md](references/preset-naming-convention.md)

- 文章封面（2.35:1）→ `1xx` (如 `101.json`)
- 小红书（3:4）→ `2xx` (如 `201.json`)
- 视频封面（16:9）→ `3xx` (如 `301.json`)
- 方形（1:1）→ `4xx` (如 `401.json`)
- OG 分享（1.91:1）→ `5xx` (如 `501.json`)

{
  "code": "007",
  "name": "My Template",
  "size": { "width": 1200, "height": 630 },
  "ratio": "1.91:1",
  "template": "[Name]",
  "contentProps": { "content": [[...]] },
  "styleProps": {
    "bgColor": "#FFFFFF",
    "bgImage": "linear-gradient(...)",
    "textWrapBgColor": "transparent",
    "textWrapPadding": "0px",
    "colors": ["#000000"],
    "accentColors": ["#FF0000"],
    "fontSizes": ["48px"],
    "aligns": ["justify-center"],
    "verticalAligns": ["center"],
    "fontFamily": "YouSheBiaoTiHei",
    "padding": "60px"
  }
}

关键字段：

• template: 必须与 templateStrings 的 key 一致
• styleProps: 必须包含所有 12 个必需字段（见蓝图文档）

3.4 测试验证

# 启动开发服务器（如未运行）
pnpm dev

# 访问测试 URL
http://localhost:4573/[code]/default
http://localhost:4573/[code]/测试文本*强调*内容

使用质量检查清单： checklist.md

---

🐛 Production Debugging & Common Pitfalls

Critical Issue: Satori atob() Errors in Production

If you encounter InvalidCharacterError: Invalid character at atob in production (but works locally), follow this diagnostic checklist:

Issue 1: Buffer Type Mismatch in Nitro Storage

Symptom:

[Image] Invalid base64 characters detected: 137,80,78,71,13,10...

Root Cause:

• Nitro's storage.getItemRaw<Buffer>() may return Uint8Array or plain objects in production
• These don't have .toString('base64') method
• Results in raw byte arrays instead of base64 strings

Fix (server/utils/image-loader.ts):

// ❌ WRONG: Assumes buffer is always Buffer
const base64 = buffer.toString('base64')

// ✅ CORRECT: Defensive type conversion
const properBuffer = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer)
const base64 = properBuffer.toString('base64')
const dataUrl = `data:${mimeType};base64,${base64}`

// Add diagnostic logging
console.log('[ImageLoader] Base64 preview:', base64.substring(0, 50))
console.log(`[ImageLoader] type: ${properBuffer.constructor.name}`)

Issue 2: Satori CSS backgroundImage Bug (Issue #609)

Symptom:

InvalidCharacterError: Invalid character
    at atob (node:buffer:1292:13)
    at ef (satori/dist/index.js:3:49379)

Root Cause:

• Known Satori bug with backgroundImage: url(data:image/...;base64,...)
• CSS parser's atob() fails on certain base64 formats
• Issue: https://github.com/vercel/satori/issues/609

Fix: Use <img> instead of backgroundImage

// ❌ AVOID: CSS backgroundImage with data URLs
<div :style="{ backgroundImage: `url(${logoUrl})` }"></div>

// ✅ RECOMMENDED: Direct img element
<img :src="logoUrl" :style="{ objectFit: 'cover' }" />

Why <img> works better:

• Bypasses CSS parser entirely
• Uses Satori's image handler directly
• Better error handling and logging

Issue 3: Invalid Tailwind Classes

Symptom:

`nowrap` unknown or invalid utility

Fix:

// ❌ WRONG: Not a valid Tailwind class
<span class="text-nowrap flex">

// ✅ CORRECT: Valid Tailwind class
<span class="whitespace-nowrap flex">

Invalid CSS classes can interfere with Satori's template parsing.

Issue 4: btoa() Server-Side Encoding

Symptom:

• Works locally but fails in production
• atob() errors with SVG icons

Root Cause:

• btoa() is a browser API, unreliable in Node.js
• Treats input as Latin-1, not UTF-8
• Produces incorrect encoding for non-ASCII characters

Fix (server/utils/icons.ts, lib/icons.ts):

// ❌ WRONG: Browser API in server code
const base64 = btoa(svgHTML)

// ✅ CORRECT: Node.js Buffer API
const base64 = Buffer.from(svgHTML, 'utf8').toString('base64')

Issue 5: bgColor=transparent Renders as Black

Symptom:

• URL param ?bgColor=transparent produces black background instead of transparent
• Other CSS color keywords (inherit, currentColor) also fail

Root Cause:

• paramNormalizer.ts auto-adds # prefix to all color values
• transparent becomes #transparent (invalid color)
• Satori/browsers render invalid colors as black

Fix (server/utils/paramNormalizer.ts):

// In normalizeValue() for COLOR_PROPS
if (COLOR_PROPS.has(key)) {
  if (strValue.startsWith('#')) {
    return strValue
  }
  // ✅ NEW: Preserve CSS color keywords
  const cssColorKeywords = ['transparent', 'inherit', 'currentColor', 'none']
  if (cssColorKeywords.includes(strValue.toLowerCase())) {
    return strValue.toLowerCase()
  }
  return `#${strValue}`
}

Usage:

# ✅ Now works correctly
GET /api/104/text?bgColor=transparent
GET /api/104/text?bgColor=inherit

Issue 6: Query String Corruption (+ → space)

Symptom:

[Image] Base64 contains whitespace - sanitizing

Root Cause:

• If base64 data URLs are passed via query string
• URL form-encoding converts + to space
• atob() rejects base64 with whitespace

Fix (server/utils/image.ts):

// Add sanitization before Satori rendering
if (styleFinalProps.logoUrl?.startsWith('data:')) {
  const idx = styleFinalProps.logoUrl.indexOf(',');
  if (idx !== -1) {
    const head = styleFinalProps.logoUrl.slice(0, idx + 1);
    let body = styleFinalProps.logoUrl.slice(idx + 1);
    
    // Remove whitespace corruption
    if (/\s/.test(body)) {
      console.warn('[Image] Base64 contains whitespace - sanitizing');
      body = body.replace(/\s+/g, '');
    }
    
    // Validate charset
    if (!/^[A-Za-z0-9+/=]+$/.test(body)) {
      throw createError({ 
        statusCode: 500, 
        statusMessage: 'Invalid image data encoding' 
      });
    }
    
    styleFinalProps.logoUrl = head + body;
  }
}

Prevention:

• Avoid passing data URLs in query strings
• Use asset paths instead: logoPath=images/logo.png
• Or use POST with JSON body (preserves + characters)

Diagnostic Techniques

1. Add Logging at Key Points:

// In image-loader.ts
console.log('[ImageLoader] Base64 preview:', base64.substring(0, 50))
console.log('[ImageLoader] Buffer type:', buffer.constructor.name)

// In image.ts
console.log('[Image] logoUrl preview:', styleFinalProps.logoUrl?.substring(0, 60))

// In satori.ts
console.log('[Satori] Rendering HTML length:', html.length)

2. Check Production Logs:

✅ Success Pattern:

[ImageLoader] Base64 preview: iVBORw0KGgoAAAANSUhEU...
[ImageLoader] type: Buffer

❌ Failure Pattern:

[Image] Invalid base64 characters: 137,80,78,71...

→ Indicates Buffer serialization issue

3. Verify Base64 Integrity:

# Extract base64 from logs and test decode
echo "iVBORw0KGgoAAAA..." | base64 -d | file -
# Should show: PNG image data

Best Practices Summary

When to Escalate

If after applying all fixes you still see atob() errors:

1. Check Satori version: Update to latest (npm ls satori)
2. Inspect actual HTML: Log rendered HTML before Satori
3. Test SVG rendering: Try pure SVG output (format=svg)
4. File upstream bug: Search https://github.com/vercel/satori/issues
5. Workaround: Switch from Satori to Puppeteer/Playwright for complex cases

---

📚 完整文档索引

核心概念（必读）

• 架构说明 - 模板系统设计原理
• Satori 约束 - 渲染引擎限制
• Props 系统 - 数据结构详解

模板蓝图（按需选择）

• 简单文本模板
• 多行布局模板
• 强调文本模板
• 渐变背景模板
• 图标模板
• 像素矩阵模板

辅助资料（问题查询）

• 常见模式库 - 15+ 设计模式和代码片段
• 故障排除指南 - 10 个常见问题及解决方案
• 质量检查清单 - 22 个检查项

示例演示（学习参考）

• CleanTitle 完整演示 - 端到端工作流
• 模板对比分析 - 现有模板特点

---

⚠️ 关键规则（禁止事项）

❌ 不要创建这些文件

1. components/template/*.vue - 已废弃，Satori 无法使用 Vue 组件
2. lib/template.ts - 已废弃，注册表未被调用
3. 任何 .vue 文件作为模板 - 必须使用 .ts 模板字符串

❌ 不要使用这些 CSS

1. box-shadow - Satori 不支持阴影效果
2. transform - Satori 不支持变换（旋转/缩放）
3. filter - Satori 不支持滤镜
4. animations - 静态图片无法展示动画
5. z-index - 通过 DOM 顺序控制层级

✅ 必须遵守

1. 所有元素必须 flex - 添加 class="flex"
2. 包含所有必需 styleProps - 12 个字段缺一不可
3. 测试后再提交 - 使用质量检查清单验证
4. 遵循蓝图结构 - 不要随意修改模板结构

---

🎯 工作流程图

用户需求
   ↓
📖 阅读架构文档（architecture.md, satori-constraints.md, props-system.md）
   ↓
🎨 选择蓝图（simple-text / multi-line / accent / gradient / icons）
   ↓
📝 阅读蓝图文档（了解完整代码和配置）
   ↓
💻 创建 server/templates/[Name].ts
   ↓
⚙️ 注册到 server/utils/image.ts
   ↓
📦 创建 presets/[code].json
   ↓
🧪 测试 http://localhost:4573/[code]/default
   ↓
✅ 质量检查（checklist.md）
   ↓
🎉 完成！

---

💡 快速决策树

需求分析 → 蓝图选择

问题 1: 是否需要强调特定文字（高亮/背景盒子）？
  ├─ 是 → 🎨 使用 blueprint-with-accent.md
  └─ 否 → 继续

问题 2: 是否需要渐变背景或复杂背景效果？
  ├─ 是 → 🌈 使用 blueprint-with-gradient.md
  └─ 否 → 继续

问题 3: 是否需要显示图标或 emoji？
  ├─ 是 → 🎯 使用 blueprint-with-icons.md
  └─ 否 → 继续

问题 4: 是否需要像素艺术风格（用色块/emoji拼成图案）？
  ├─ 是 → 🧱 使用 blueprint-pixel-matrix.md
  └─ 否 → 继续

问题 5: 是否需要多行文本且每行样式不同？
  ├─ 是 → 📋 使用 blueprint-multi-line.md
  └─ 否 → 📝 使用 blueprint-simple-text.md

---

🔗 外部资源

• Satori 官方文档
• Tailwind CSS 文档
• Vue 3 模板语法

---

📊 文档统计

• 总文档数: 15 个
• 核心文档: 3 个（架构、Satori、Props）
• 蓝图库: 6 个（覆盖所有常见场景）
• 辅助资料: 3 个（模式、故障、清单）
• 示例演示: 2 个（学习参考）

---

🎓 学习路径建议

新手（首次使用）

1. 必读：架构说明（2 分钟）
2. 必读：Satori 约束（3 分钟）
3. 选择：简单文本蓝图（5 分钟）
4. 实践：跟随蓝图创建第一个模板
5. 验证：使用质量检查清单

预计时间：30 分钟完成第一个模板

进阶（第二个模板开始）

1. 回顾：Props 系统（理解数据流）
2. 选择：根据需求选择蓝图
3. 参考：常见模式库（复用代码片段）
4. 调试：故障排除指南（遇到问题时查阅）

预计时间：15 分钟完成新模板

---

✅ 成功标准

一个合格的模板必须满足：

1. ✅ 访问 /{code}/default 正常显示
2. ✅ 样式符合设计要求
3. ✅ 浏览器控制台无 Vue 警告
4. ✅ 无 Satori 渲染错误
5. ✅ 代码通过质量检查清单
6. ✅ 测试不同内容均正常渲染

---

开始前必读： 架构说明 → Satori 约束 → 选择蓝图

遇到问题？ 查阅 故障排除指南 或 Production Debugging