Twikoo 评论系统集成 Cloudflare ImgBed 图床指南

Twikoo + Cloudflare ImgBed 图床配置指南

一、概述

本指南介绍如何在 Twikoo 评论系统中集成 Cloudflare ImgBed 图床，实现图片上传功能。

适用场景

  • 使用 Vercel 部署 Twikoo
  • 需要将评论中的图片上传到云存储
  • 使用 Cloudflare ImgBed 作为图床服务

二、修改的源码文件

文件 说明
src/server/function/twikoo/utils/image.js cfimgbed 上传逻辑实现
src/server/function/twikoo/package.json npm 包版本号
src/server/vercel/package.json 依赖 twikoo-func-yokipeek
src/server/vercel/api/index.js require 路径改为 twikoo-func-yokipeek

三、发布 npm 包

1. 修改版本号

编辑 src/server/function/twikoo/package.json，将 version 改为新版本号（如 1.7.15）。

2. 配置 npm 认证

在 src/server/function/twikoo/ 目录下创建 .npmrc 文件：

1
//registry.npmjs.org/:_authToken=你的_npm_automation_token

Token 获取方式：

  1. 登录 https://www.npmjs.com
  2. 进入 Settings > Tokens
  3. Generate New Token > Automation
  4. 勾选 “Allow packages with 2FA enabled to be published without 2FA”
  5. 复制生成的 token

3. 发布包

1
2
cd src/server/function/twikoo
npm publish --access public

4. 更新 Vercel 依赖

编辑 src/server/vercel/package.json，将 twikoo-func-yokipeek 版本改为刚发布的版本号。

四、Vercel 部署配置

  1. 登录 Vercel，进入你的项目
  2. 点击 Settings > General
  3. Root Directory 设置为 src/server/vercel
  4. 不需要设置 Build Command（Vercel 自动处理）

五、环境变量配置

在 Vercel Settings > Environment Variables 中添加：

变量名 说明 示例
MONGODB_URI MongoDB 连接字符串 mongodb+srv://user:pass@cluster.xxx.mongodb.net/twikoo
IMAGE_CDN 图床类型，固定值 cfimgbed
IMAGE_CDN_URL cfimgbed API 地址 https://cfbed.sanyue.de 或 https://img.weiguang.eu.org
IMAGE_CDN_TOKEN 认证令牌 详见下方配置方式

六、IMAGE_CDN_TOKEN 配置方式

方式1：直接填 authCode（简单模式）

适用于使用 authCode 认证的场景：

1
IMAGE_CDN_TOKEN = your_auth_code_here

方式2：JSON 完整配置（推荐）

适用于需要指定更多参数的场景：

1
2
3
4
5
6
7
8
9
10
{
  "authCode": "your_auth_code",
  "uploadChannel": "telegram",
  "useBearerAuth": false,
  "uploadNameType": "origin",
  "channelName": "",
  "serverCompress": true,
  "autoRetry": true,
  "uploadFolder": ""
}

或使用 Bearer Token 认证：

1
2
3
4
5
6
{
  "token": "your_api_token",
  "uploadChannel": "discord",
  "useBearerAuth": true,
  "uploadNameType": "origin"
}

JSON 配置参数说明

参数 类型 默认值 说明
authCode string - 上传认证码（与 token 二选一）
token string - API Token（与 authCode 二选一）
apiKey string - API Key（与 authCode 或 token 二选一）
uploadChannel string telegram 上传渠道，可选值：telegram、discord、cfr2、s3、huggingface
useBearerAuth boolean false 是否使用 Authorization: Bearer 方式认证
uploadNameType string origin 文件命名方式：default（前缀_原名）、index（仅前缀）、origin（仅原名）、short（短链接）
channelName string - 指定渠道名称（多渠道场景），可通过 /api/channels 获取可用列表
serverCompress boolean true 服务端压缩（仅 Telegram 渠道图片）
autoRetry boolean true 失败时自动切换渠道重试
uploadFolder string - 上传目录，相对路径，如 twikoo

七、认证方式说明

authCode 认证（默认）

图床 API 使用 authCode 作为 Query 参数认证：

1
POST /upload?authCode=xxx&uploadChannel=telegram

配置示例：

1
2
3
4
{
  "authCode": "your_auth_code",
  "useBearerAuth": false
}

Bearer Token 认证

图床 API 使用 Authorization: Bearer Header 认证：

1
Authorization: Bearer your_api_token

配置示例：

1
2
3
4
{
  "token": "your_api_token",
  "useBearerAuth": true
}

注意：useBearerAuth 必须设为 true 才能生效。

八、uploadChannel 渠道说明

渠道 说明 文件限制
telegram 默认渠道，通过 Telegram Bot 上传 单文件 20MB
discord 通过 Discord 上传 免费用户 10MB，Nitro 25MB
cfr2 Cloudflare R2 存储 无限制
s3 AWS S3 或兼容存储 无限制
huggingface HuggingFace 存储 支持大文件直传

九、常见问题

1. 图片上传失败：undefined

原因：API 响应格式不符合预期。

排查：检查 Vercel Logs 查看实际响应内容。

2. FUNCTION_PAYLOAD_TOO_LARGE

原因：Vercel Function 请求体限制约 4.5MB，图片过大会触发此错误。

解决方案：

  • 用户上传前手动压缩图片
  • 调整 Twikoo 前端压缩参数（需修改源码并重新构建）

3. 图片显示为相对路径

原因：未设置 returnFormat=full。

解决：代码已默认添加此参数，如仍有问题请检查图床 API 是否支持此参数。

4. 认证失败

检查：

  • 确认 authCode 或 token 是否正确
  • 确认 useBearerAuth 设置是否正确（Bearer 认证需设为 true）
  • 检查图床后台是否启用了对应的认证方式

十、测试验证

  1. 部署完成后访问你的 Vercel 域名，确认返回版本信息
  2. 进入 Twikoo 管理面板（评论框小齿轮图标）
  3. 配置图床选项，选择 cfimgbed
  4. 填写 IMAGE_CDN_URL 和 IMAGE_CDN_TOKEN
  5. 尝试上传图片，检查是否成功

十一、版本更新流程

当需要更新代码时：

  1. 修改 src/server/function/twikoo/utils/image.js
  2. 更新 src/server/function/twikoo/package.json 版本号
  3. 发布 npm 包
  4. 更新 src/server/vercel/package.json 依赖版本
  5. 推送代码，Vercel 自动重新部署

十二、完整配置示例

示例1：使用 Telegram 渠道 + authCode 认证

1
2
3
4
5
{
  "authCode": "your_auth_code",
  "uploadChannel": "telegram",
  "uploadNameType": "origin"
}

示例2：使用 Discord 渠道 + Bearer Token 认证

1
2
3
4
5
6
{
  "token": "imgbed_xxxxxxxxxxxx",
  "uploadChannel": "discord",
  "useBearerAuth": true,
  "uploadNameType": "origin"
}

示例3：指定上传目录

1
2
3
4
5
{
  "authCode": "your_auth_code",
  "uploadChannel": "telegram",
  "uploadFolder": "blog/comments"
}

示例4：禁用服务端压缩

1
2
3
4
5
{
  "authCode": "your_auth_code",
  "uploadChannel": "telegram",
  "serverCompress": false
}