流星雨人机验证 - 对接文档

快速开始

三种方式接入，最快只需一行代码

零 JS 接入 -- 最简方式

只需引入 loader.js 并添加一个容器，自动完成所有初始化工作。

<div data-captcha></div>
<script src="https://meteorcaptcha.yulovehan.top/captcha/loader.js"></script>

loader.js 会自动扫描页面中所有 [data-captcha] 容器并初始化验证码组件。

注意：验证码组件需要至少 250px 宽度的容器空间。如果容器尺寸不足，会自动切换到全屏弹窗模式。

表单

表单自动集成

将验证码放在 form 内，会自动拦截表单提交，验证通过后自动注入隐藏字段。

<form action="/submit" method="POST">
  <input name="username" required>
  <div data-captcha></div>
  <button type="submit">提交</button>
</form>
<script src="https://meteorcaptcha.yulovehan.top/captcha/loader.js"></script>

验证通过后会自动注入 <input type="hidden" name="captcha_token">。

API

JS API 调用

使用 Captcha.init() 进行精细控制，支持回调函数和 Promise。

<div id="my-captcha"></div>
<script src="https://meteorcaptcha.yulovehan.top/captcha/loader.js"></script>
<script>
window.addEventListener('CaptchaLoaded', function() {
  const captcha = Captcha.init('#my-captcha', {
    onVerified: function(token) {
      console.log('验证成功:', token);
    },
    onError: function(err) {
      console.log('验证失败:', err);
    }
  });
});
</script>

Promise 方式

try {
  const result = await Captcha.verify('#my-captcha');
  console.log('验证成功:', result.token);
} catch (err) {
  console.log('验证失败:', err.message);
}

实时演示

前往在线演示

API 文档

所有接口均使用 JSON 格式通信

安全说明：Token 格式为 {tokenId}.{HMAC签名}，服务端在签发时已将目标坐标加密进签名，客户端无需关心坐标值。

POST

/api/v1/token -- 获取验证令牌

请求体

{
  "deviceFingerprint": "a1b2c3d4e5f6...",
  "origin": "https://your-site.com"
}

响应

{
  "success": true,
  "data": {
    "token": "abc123...def.sig123...",
    "targetImage": "https://unocr.yulovehan.top/api/target?token=..."
  },
  "message": "令牌生成成功"
}

服务端返回加密的 token 和目标图片 URL。客户端渲染目标图片后，用户将圆球拖拽至目标位置。

POST

/api/v1/verify -- 验证令牌

请求体

{
  "token": "abc123...def.sig123...",
  "origin": "https://your-site.com",
  "sliderBehavior": {
    "trajectory": [
      { "x": 12, "y": 8, "t": 0, "type": "start" },
      { "x": 30, "y": 20, "t": 350, "type": "move" },
      { "x": 50, "y": 50, "t": 1200, "type": "end" }
    ],
    "duration": 1200
  }
}

成功响应

{
  "success": true,
  "data": { "verified": true },
  "message": "验证成功"
}

需要二次验证响应

{
  "success": true,
  "data": {
    "needSecondVerify": true,
    "question": "请选择所有",
    "questionImage": "https://unocr.yulovehan.top/gen?id=...",
    "questionId": "q-xxx-xxx",
    "options": ["a7k2.png", "b3x9.png", "c8m4.png", "d5p7.png"]
  },
  "message": "需要二次验证"
}

二次验证时，前端弹出图片选择题弹窗，用户选择后将答案再次提交到 /api/v1/verify。

POST

/api/v1/check -- 校验令牌（主站对接）

请求体

{
  "token": "abc123...def.sig123...",
  "usage": "register"
}

成功响应

{
  "success": true,
  "data": { "valid": true },
  "message": "令牌验证通过"
}

重要：主站服务端在接收注册/登录请求时，务必调用此接口验证 token（一次性消耗），不要直接信任客户端提交的 token。

Node.js 集成示例

app.post('/api/auth/register', async (req, res) => {
  const { captcha_token, username, password } = req.body;

  const resp = await fetch('https://meteorcaptcha.yulovehan.top/api/v1/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: captcha_token, usage: 'register' })
  });
  const result = await resp.json();

  if (!result.success || !result.data?.valid) {
    return res.status(403).json({ error: '人机验证失败' });
  }

  // token 已验证且已消耗，继续注册流程
});

配置选项

组件参数与 HTML 属性

组件配置

参数	类型	默认值	说明
`apiUrl`	string	`https://meteorcaptcha.yulovehan.top`	验证服务器地址
`theme`	string	`'light'`	主题：`'light'` 或 `'dark'`
`debug`	boolean	`false`	调试模式
`mock`	boolean	`false`	模拟模式（跳过真实验证）
`autoVerify`	boolean	`false`	是否自动验证
`onVerified`	function	-	验证成功回调
`onError`	function	-	验证失败回调

HTML 属性

属性	说明
`data-captcha`	标记为验证容器（必须）
`data-captcha-api`	API 地址
`data-captcha-theme`	主题：light / dark
`data-captcha-debug`	调试模式：true
`data-captcha-mock`	模拟模式：true
`data-captcha-onverified`	验证成功回调函数名
`data-captcha-onerror`	验证失败回调函数名