如何在 Vercel 上搭建并部署 claude-code-templates 的 Discord 组件搜索机器人？

如何在 Vercel 上搭建并部署 claude-code-templates 的 Discord 组件搜索机器人？

【免费下载链接】claude-code-templatesCLI tool for configuring and monitoring Claude Code项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-templates

claude-code-templates 项目提供了一个 Discord 组件搜索机器人，它不依赖常驻连接，而是以 Vercel 服务端函数（Serverless Function）的形式运行：只有当用户在 Discord 中触发命令时，Discord 才会通过 webhook 把请求推送到你的部署地址。部署完成后，这个机器人在你的 Discord 服务器中提供/search、/info、/install、/popular、/random五个斜杠命令，用于搜索平台组件数据（skills、agents、commands、mcps、settings、hooks、templates、plugins 等类型）并以 embed 消息返回结果。

本文的操作流程来自仓库内的部署指南 docs/guides/discord-bot-setup.md，完整路径是：创建 Discord 应用并获取三个密钥 → 配置环境变量 → 注册斜杠命令 → 部署到 Vercel → 在 Discord 绑定 Interactions Endpoint → 邀请机器人进服务器。

部署架构与可用命令

指南明确说明，选择 Vercel Functions 的动机是：没有永久服务器、Vercel 自动处理扩缩容、机器人与项目本身在同一仓库中一并部署、只为实际执行付费，并且函数之间会复用数据缓存。

一次交互的完整链路是：用户在 Discord 输入/search security→ Discord 向https://your-domain.vercel.app/api/discord/interactions发送 POST 请求 → Vercel 执行交互端点 → 端点先校验请求签名（安全验证）→ 识别命令并交给对应 handler → handler 加载 components.json（优先用缓存）→ 执行搜索并生成 embed → 返回给 Discord 展示给用户。

组件数据缓存机制：系统在内存中保留 components.json 5 分钟。首次请求从 aitmpl.com 下载；5 分钟内的后续请求直接使用缓存；超过 5 分钟后自动刷新，以此降低延迟和对 API 的请求量。

五个斜杠命令及其用途如下（以指南给出的注册输出描述为准）：

第一步：创建 Discord 应用并获取三个密钥

在 Discord Developer Portal（开发者后台）完成以下操作，这三个值就是后面所有环境变量的来源：

1. 点击 "New Application" 创建应用并命名。
2. 在 "General Information" 页面复制Application ID，即DISCORD_APP_ID。
3. 进入 "Bot" 页面，点击 "Add Bot"，复制Bot Token，即DISCORD_BOT_TOKEN；如需要，勾选启用 "Message Content Intent"。
4. 回到 "General Information"，复制Public Key，即DISCORD_PUBLIC_KEY。

如果你只想在特定服务器里测试，还可以记下该服务器的 ID 作为DISCORD_GUILD_ID（可选，指南建议在测试阶段使用，生产环境移除）。

第二步：配置环境变量

本地测试用.env

指南给出的本地.env示例如下。注意：下面全部是文档中的示例值，必须替换为你在上一步从 Developer Portal 复制到的真实密钥：

# Discord Bot Configuration DISCORD_APP_ID=123456789012345678 DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4.AbCdEf.GhIjKlMnOpQrStUvWxYz DISCORD_PUBLIC_KEY=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 DISCORD_GUILD_ID=987654321098765432 # Opcional, para testing en un server específico # API Configuration COMPONENTS_API_URL=https://aitmpl.com/components.json

Vercel 生产环境

进入 Vercel Dashboard 中你的项目，在 Settings → Environment Variables 中添加：

• DISCORD_APP_ID
• DISCORD_BOT_TOKEN
• DISCORD_PUBLIC_KEY
• COMPONENTS_API_URL（可选，默认使用 aitmpl.com）

第三步：安装依赖并注册斜杠命令

执行：

npm install

指南说明这一步会安装三个关键依赖：discord-interactions（校验来自 Discord 的请求）、axios（加载 components.json）、dotenv（读取环境变量）。

然后注册命令：

npm run discord:register

成功时的输出如下（文档示例输出）：

📦 Registering Discord slash commands... Registering to guild: 987654321098765432 ✅ Successfully registered 5 commands! 📝 Registered commands: 1. /search - Search for components by keyword 2. /info - Get detailed information about a specific component 3. /install - Get the installation command for a component 4. /popular - View the most popular components by download count 5. /random - Discover a random component

如果配置了DISCORD_GUILD_ID，命令只会注册到该服务器；后续排查"命令不出现"问题时这一点很关键。

第四步：部署到 Vercel 并绑定 Interactions Endpoint

vercel --prod

也可以在配置了 GitHub 集成的情况下依赖自动部署。vercel --prod会把当前项目发布为 Vercel 生产部署，部署前确保上一步的环境变量已在 Vercel Dashboard 中配置。

部署成功后复制你的生产 URL（形如https://your-project.vercel.app），然后在 Discord Developer Portal → 你的应用 → "General Information" 中，把Interactions Endpoint URL设置为：

https://your-project.vercel.app/api/discord/interactions

其中your-project替换为你的实际 Vercel 项目域名。点击 "Save Changes" 后，Discord 会向该地址发送 PING 验证；配置正确时会看到 ✅ 标记。也可以用 curl 手动确认端点可达（同样把your-domain替换为实际域名）：

curl https://your-domain.vercel.app/api/discord/interactions

第五步：邀请机器人到你的服务器

1. 在 Developer Portal 进入 OAuth2 → URL Generator。
2. Scopes 勾选：bot、applications.commands。
3. Bot 权限勾选：Send Messages、Embed Links、Read Message History。
4. 复制生成的 URL 并在浏览器打开，选择目标服务器完成授权。

打开该 URL 的副作用是：机器人会被授权加入你选择的服务器并获得上述权限，请确认所选服务器和权限范围符合预期。

可选分支：部署前本地测试

指南提供了一条在部署前本地验证的路径，全部为可选项：

# 1. 如尚未安装 Vercel CLI（该命令会全局安装 vercel CLI） npm i -g vercel # 2. 启动开发服务器 vercel dev

服务会运行在http://localhost:3000。由于 Discord 无法直接访问你的 localhost，需要用隧道把本地端口暴露出去（ngrok 会把本地 3000 端口临时映射为一个公网地址，测试结束后记得停止隧道）：

# Opción 1: ngrok ngrok http 3000 # Opción 2: Vercel dev con --listen vercel dev --listen 3000

把隧道的公网 URL 填到 Discord 的 Interactions Endpoint 即可完成本地联调。

验证方式与常见问题排查

正常运行如何确认

• Endpoint 绑定后 Discord 显示 ✅，说明 PING 校验通过。
• 在 Vercel Dashboard → Functions 中查看调用量、错误数、响应时间和实时日志。
• 每次命令执行会在控制台记录日志，文档示例输出为：

🔹 Command received: /search ✅ Components data loaded

在 Vercel Functions 的日志里检索这些记录即可确认命令链路跑通。

常见问题

"Invalid request signature"（签名无效）：原因是DISCORD_PUBLIC_KEY未配置或抄错。依次检查 Vercel 环境变量中的DISCORD_PUBLIC_KEY、确认是从 Developer Portal 复制的 Public Key，修改环境变量后重新部署。

Discord 无法验证 URL：原因是端点没有正确响应 PING。先确认部署成功，再用上面的 curl 命令手动测试端点，然后在 Vercel Dashboard → Functions 查看日志。

命令在 Discord 中不出现：重新执行npm run discord:register；如果注册时用了DISCORD_GUILD_ID，命令只在那个服务器可见；可以把机器人移出服务器后带着applications.commandsscope 重新邀请；全局命令最长可能要等 1 小时才显示。

机器人不响应：查看 Vercel Functions 日志；确认机器人有 "Send Messages" 和 "Embed Links" 权限；先用/random这类简单命令试一下。

"Components data not loaded"：确认 components.json 数据源可访问；如果配置了自定义COMPONENTS_API_URL，检查该变量值；到 Vercel 日志中查看具体错误。

限制与生产环境注意事项

• 测试阶段保留DISCORD_GUILD_ID可在指定服务器快速调试；上生产前移除它，命令才会全局注册。
• 全局命令的显示延迟最长可达 1 小时，这不是部署失败。
• 所有错误都会以 ephemeral embed 返回（仅调用者本人可见）。
• 5 分钟的组件缓存时长可按需调整，指南指出的位置是componentsLoader.js中的CACHE_DURATION。
• 指南列出的后续演进方向（尚未包含在本文部署范围内）：第二阶段的/stats、/new、/daily命令，第三阶段的按钮、下拉菜单和表单，以及第四阶段的安装追踪与 release 通知。

【免费下载链接】claude-code-templatesCLI tool for configuring and monitoring Claude Code项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-templates