Hexo 看板娘接入 AI 聊天

发表于 2026-06-22 分类于 AI Waline：

记录从 Cloudflare Workers AI 开通、Worker 接口部署，到 Hexo 前端调用 AI 回复的完整接入过程。

这篇记录的是怎么把 Hexo 博客里的 Live2D 看板娘接入 AI 聊天。重点放在 Cloudflare Workers AI 怎么开通、Worker 接口怎么写、前端怎么请求，让没有接过的人也能照着步骤做一遍。

这次接入的整体结构很简单：

博客页面收集用户输入。
前端把问题发送到自己的 Cloudflare Worker。
Worker 调用 Cloudflare Workers AI。
模型返回内容以后，Worker 再把结果返回给博客前端。

这里用 Worker 做一层中转，前端只请求自己的接口，真正调用模型的逻辑放在 Cloudflare 那边。

下面按实际接入顺序记录一遍。

先注册 Cloudflare 账号

如果之前没有用过 Cloudflare，可以先从账号开始。

打开 Cloudflare 官网：https://dash.cloudflare.com。
如果没有账号，点击页面里的 Sign up 注册。
输入邮箱和密码以后，按提示完成邮箱验证。
验证完成后回到 https://dash.cloudflare.com 登录。
登录成功后会进入 Cloudflare Dashboard，也就是 Cloudflare 的控制台。

这一步不需要先买域名，也不需要先开通付费套餐。
Workers 和 Workers AI 都可以先用免费额度跑起来，博客这种轻量聊天场景比较适合先从免费额度开始试。

创建一个 Worker

账号准备好以后，先创建 Worker。
Worker 就是 Cloudflare 提供的边缘函数，可以理解成一个很轻量的后端接口。

在 Cloudflare Dashboard 里按下面这样点：

左侧菜单找到 Workers & Pages。
进入后点击 Create 或 Create application。
选择 Workers。
如果页面让你选择模板，可以选 Hello World。
填一个 Worker 名字，比如 chensheng-blog-waifu-ai。
点击 Deploy。

部署成功后，Cloudflare 会给你一个 workers.dev 地址。
这个地址后面就是前端要请求的接口域名。

第一次创建 Worker 的目的，是先确认账号里的 Workers 功能可用。
后面真正的代码部署，我还是用本地项目里的 wrangler 来管理，这样更适合放进博客项目一起维护。

开通 Workers AI

接着打开 Workers AI。
Workers AI 是 Cloudflare 提供的模型运行能力，Worker 里可以直接通过绑定对象调用模型。

在 Dashboard 里可以这样找：

左侧菜单找到 AI。
点击 Workers AI。
如果页面出现 Get started、Enable Workers AI 或类似按钮，就点进去确认开通。
开通后页面一般能看到模型列表、使用量、Playground 之类的内容。

这里有一点要注意：
Workers AI 不是在前端生成一个 API Key 然后拿去调用。
它更推荐的方式是把 AI 能力绑定到 Worker 上，在 Worker 代码里通过 env.AI.run() 调模型。

也就是说，前端请求的是你的 Worker：

1	博客前端 -> Cloudflare Worker -> Workers AI -> Cloudflare Worker -> 博客前端

这样前端不需要保存任何模型密钥。

本地安装 Wrangler

Cloudflare 的 Worker 可以在网页上编辑，但正式项目里更建议用本地代码管理。
这里需要安装 Cloudflare 官方命令行工具 wrangler。

在博客项目里安装：

1	npm install -D wrangler

然后登录 Cloudflare：

1	npx wrangler login

执行后会自动打开浏览器。
浏览器里登录 Cloudflare，然后点击授权按钮，让 Wrangler 可以部署你的 Worker。

授权完成后，可以用下面命令确认当前登录的是哪个账号：

1	npx wrangler whoami

为了后面使用方便，我在 package.json 里加了几个脚本：

{
  "scripts": {
    "ai:dev": "wrangler dev -c wrangler.waifu-ai.toml",
    "ai:deploy": "wrangler deploy -c wrangler.waifu-ai.toml",
    "ai:whoami": "wrangler whoami"
  }
}

之后就可以用 npm run ai:deploy 来部署 AI Worker。

配置 Wrangler

接着在项目根目录新建一个 Worker 配置文件。
我这里用的是 wrangler.waifu-ai.toml：

name = "chensheng-blog-waifu-ai"
main = "workers/waifu-ai-worker.js"
compatibility_date = "2026-06-22"

[ai]
binding = "AI"

几个字段分别是：

name：Worker 的名称，也会影响默认的 workers.dev 地址。
main：Worker 入口文件。
compatibility_date：Cloudflare Workers 的兼容日期，可以写当前日期。
[ai] binding = "AI"：把 Workers AI 绑定到 Worker 里，代码里就可以用 env.AI 调用模型。

如果你想在 Cloudflare 网页里检查绑定，也可以打开对应 Worker：

进入 Workers & Pages。
点击你的 Worker。
进入 Settings。
找到 Bindings。
如果手动添加，选择 Add binding。
类型选择 Workers AI。
变量名填 AI。
保存并重新部署。

用 wrangler.waifu-ai.toml 配好以后，部署时一般会按配置自动处理这个绑定。
网页里主要是用来检查配置有没有生效。

编写 Worker 接口

然后创建 Worker 入口文件：

1	workers/waifu-ai-worker.js

核心代码可以按下面这个结构写：

const ALLOWED_ORIGINS = new Set([
  'https://www.chensheng.group',
  'http://localhost:4000',
  'http://127.0.0.1:4000'
]);

function createCorsHeaders(request) {
  const origin = request.headers.get('Origin') || '';
  const allowOrigin = ALLOWED_ORIGINS.has(origin)
    ? origin
    : 'https://www.chensheng.group';

  return {
    'Access-Control-Allow-Origin': allowOrigin,
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type',
    'Content-Type': 'application/json; charset=utf-8'
  };
}

export default {
  async fetch(request, env) {
    const headers = createCorsHeaders(request);

    if (request.method === 'OPTIONS') {
      return new Response(null, { headers });
    }

    const url = new URL(request.url);

    if (url.pathname !== '/api/waifu-chat') {
      return new Response(JSON.stringify({ error: 'Not found' }), {
        status: 404,
        headers
      });
    }

    if (request.method !== 'POST') {
      return new Response(JSON.stringify({ error: 'Method not allowed' }), {
        status: 405,
        headers
      });
    }

    const body = await request.json().catch(() => ({}));
    const messages = Array.isArray(body.messages)
      ? body.messages
          .filter(item => item && typeof item.content === 'string')
          .slice(-8)
          .map(item => ({
            role: item.role === 'assistant' ? 'assistant' : 'user',
            content: item.content.trim().slice(0, 800)
          }))
          .filter(item => item.content)
      : [];

    if (!messages.length) {
      return new Response(JSON.stringify({ error: 'Message is required' }), {
        status: 400,
        headers
      });
    }

    const result = await env.AI.run('@cf/meta/llama-3.2-3b-instruct', {
      messages: [
        {
          role: 'system',
          content: '你是博客里的 AI 小助手，回答要简短、自然，适合显示在网页的小气泡里。'
        },
        ...messages
      ],
      max_tokens: 220
    });

    return new Response(JSON.stringify({
      reply: result.response || '我刚刚没有想好怎么回答，可以再问我一次。'
    }), {
      headers
    });
  }
};

这段代码主要做了几件事：

处理跨域，让博客域名和本地 4000 调试地址可以请求。
只开放 /api/waifu-chat 这个接口。
只允许 POST 请求。
从请求体里读取 messages，只保留最近几条历史消息。
用 env.AI.run() 调用 Workers AI 模型。
把模型返回的内容整理成 { reply: '...' } 返回给前端。

这里使用的模型是：

1	@cf/meta/llama-3.2-3b-instruct

它不是最大的模型，但博客聊天这种场景够用了。
这类功能更看重返回速度、成本和稳定性，不需要一上来就用特别大的模型。

部署 Worker

配置和代码都准备好以后，就可以部署：

1	npm run ai:deploy

如果没有配脚本，也可以直接执行：

1	npx wrangler deploy -c wrangler.waifu-ai.toml

部署成功后，终端会输出一个地址。
把这个地址后面加上 /api/waifu-chat，就是前端要调用的接口。

例如：

1	https://chensheng-blog-waifu-ai.328921371.workers.dev/api/waifu-chat

先测试接口

前端接入之前，先测试 Worker 接口是否能正常返回。
在 PowerShell 里可以这样测：

$body = @{
  messages = @(
    @{
      role = "user"
      content = "你好"
    }
  )
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
  -Uri "https://chensheng-blog-waifu-ai.328921371.workers.dev/api/waifu-chat" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

如果返回里有 reply 字段，就说明 Worker 和 Workers AI 已经接通了。

这一步很重要。
先把后端接口测通，再去改前端，排查问题会简单很多。
如果这一步都不通，一般优先检查下面几点：

wrangler 是否已经登录成功。
wrangler.waifu-ai.toml 里有没有 [ai] binding = "AI"。
Worker 里调用的是不是 env.AI.run()。
请求地址有没有带上 /api/waifu-chat。
Cloudflare Dashboard 里 Workers AI 是否已经开通。

前端接入 Hexo 看板娘

后端接口确认可用以后，再改 Hexo 前端。
这次主要改的是：

1	source/js/live2d-widget-autoload.js

先在前端保存 Worker 地址：

1	const WAIFU_CHAT_API = 'https://chensheng-blog-waifu-ai.328921371.workers.dev/api/waifu-chat';

然后封装一个请求方法：

const waifuChatMessages = [{
  role: 'assistant',
  content: '你好，我是小兰。想问什么都可以，我会直接在这里回你。'
}];

async function requestWaifuChat(messages) {
  const response = await fetch(WAIFU_CHAT_API, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: messages.slice(-8)
    })
  });

  if (!response.ok) {
    throw new Error('AI request failed');
  }

  const data = await response.json();
  return data.reply || '我刚刚没有想好怎么回答，可以再问我一次。';
}

用户发送一句话以后，把用户消息和 AI 回复都存进一个简单的历史数组：

async function sendWaifuMessage(message) {
  waifuChatMessages.push({
    role: 'user',
    content: message
  });

  const reply = await requestWaifuChat(waifuChatMessages);

  waifuChatMessages.push({
    role: 'assistant',
    content: reply
  });

  return reply;
}

这里历史消息不要无限传。
博客里的轻量聊天只需要带最近几轮就够了，否则请求会越来越长，速度和额度都会受影响。

前端拿到 reply 后，再写回看板娘原来的显示区域即可。
真正关键的是：前端只负责收集输入和展示结果，模型调用始终放在 Worker 里。

接入顺序整理

这次真正的接入顺序可以整理成这样：

注册并登录 Cloudflare。
在 Workers & Pages 里创建一个 Worker。
在 AI -> Workers AI 里开通 Workers AI。
本地安装并登录 wrangler。
写 wrangler.waifu-ai.toml，配置 Worker 入口和 AI 绑定。
编写 workers/waifu-ai-worker.js，通过 env.AI.run() 调模型。
部署 Worker，拿到线上接口地址。
先用命令行测试接口能否返回 reply。
在 Hexo 前端请求这个接口。

按这个顺序做，问题会比较好定位。
先保证 Cloudflare Worker 能调用模型，再接前端展示，整个流程就清楚很多。

以上就是我对 Hexo 看板娘接入 Cloudflare Workers AI 的一些整理，如有错误，欢迎大佬指出。

-------------本文结束感谢您的阅读-------------