使用 EdgeOne Pages + KV 自建短网址生成器

发表于 更新于 分类于 阅读次数：
使用 EdgeOne Pages + KV 自建短网址生成器

本文介绍如何基于腾讯 EdgeOne Pages 和 EdgeOne KV 快速搭建一个生产级的短网址服务。该项目提供整套 API（无服务器 Functions）与 Next.js 前端 UI，可以部署在 EdgeOne Pages 的全球分发环境中，结合 KV 存储实现短链映射域访问统计。

项目地址

Github仓库: lm379/dwz: 基于EdgeOne Pages的短网址生成器
Demo: 短网址生成器

为什么选择 EdgeOne Pages + KV

  • EdgeOne Pages 提供静态与 Functions 混合部署能力，适合将前端静态站点与小型无服务器 API 一并部署。
  • EdgeOne KV（键值存储）延迟低、易用、支持高并发，适合短链映射（slug → URL）、反向映射（URL → slug）以及访问计数（计数器）。

核心功能概览

  • 支持任意 URL 的短链生成与自定义别名（slug）。
  • 幂等性：相同 URL 多次创建返回相同短链（通过 u:{url} 反向映射实现）。
  • /s/:slug 负责 302 重定向并自动统计访问次数。
  • 提供查询接口（/api/resolve）以获取原始 URL。

一键部署与手动部署

提示

目前 EdgeOne Pages KV 需要申请后才能用，所以请先前往官网申请KV使用权后再部署

一键部署

选择对应的站点进行部署：

中国站： EdgeOne Pages 中国站
国际站： EdgeOne Pages 国际站

手动部署

  1. 在项目设置中创建一个 KV 命名空间，命名空间名字可以随便写
  2. Fork 仓库
  3. 在 EdgeOne Pages 控制台中绑定该仓库作为项目
  4. 按步骤完成构建设置并部署
  5. 前往项目中绑定KV，KV变量名字设置为 dwz_kv 或自己在环境变量中配置的，其余环境变量按需设置
    |L
  6. 重新部署使上述配置生效

环境变量配置

变量名 说明 必填 备注
DWZ_KV_BINDING KV 命名空间绑定名（默认 dwz_kv） 否 如果你使用自定义绑定名，需要设置此项，建议保持默认即可
API_TOKEN API 访问令牌 否 启用后，通过API创建短链时需在请求头中带 token ，WEB段不受影响
PASSWORD 密码 否 启用后，创建短链接会要求输入密码（需同时设置 NEXT_PUBLIC_PASSWORD_REQUIRED）
NEXT_PUBLIC_PASSWORD_REQUIRED UI 是否显示密码框 否 设置为 true 时前端显示密码输入框（设置密码后此项必须）
NEXT_PUBLIC_ANNOUNCEMENT 页面右上角公告文本（支持 HTML标签） 否 如需使用HTML标签，云平台可能对特殊字符有限制，此时建议对全部内容进行URL编码，并使用 NEXT_PUBLIC_ANNOUNCEMENT_ENCODED 变量
NEXT_PUBLIC_ANNOUNCEMENT_ENCODED URL 编码后的公告内容，优先使用该项 否 当云平台限制特殊字符时使用
ICP 备案号 否 -

关于公告的说明

EO的环境变量不允许空格、换行或特殊字符，这会导致包含 HTML 的 NEXT_PUBLIC_ANNOUNCEMENT 无法正常传入。此时使用工具将全部内容进行URL编码后再填入环境变量 NEXT_PUBLIC_ANNOUNCEMENT_ENCODED 即可

可以使用一些在线工具生成，比如 在线URL解码编码工具_蛙蛙工具

API 快速示例

创建短链 - POST /api/shorten

请求示例（curl）：

1
2
3
curl -X POST "https://your.domain.com/api/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url","slug":"my-link"}'

注: 如设置了API_Token，创建时需要在请求头中携带 Authorization: Bearer {API_TOKEN} 或者 X-API-Token: {API_TOKEN}
不携带则会直接返回401

响应示例：

1
2
3
4
5
{
  "slug": "my-link",
  "url": "https://example.com/very/long/url",
  "shortUrl": "https://your.domain.com/s/my-link"
}

解析短链 - GET /api/resolve?slug=abc123

1
curl "https://your.domain.com/api/resolve?slug=abc123"

响应示例：

1
2
3
4
{
  "slug": "abc123",
  "url": "https://example.com/original/url"
}

短链跳转

1
GET /s/:slug 会触发 302 重定向至原始 URL，并自动增加访问计数

本地开发

  1. 安装 EdgeOne CLI
1
npm install -g edgeone
  1. 绑定项目
1
edgeone pages link
  1. 绑定 KV 命名空间后，启动本地开发服务器
1
edgeone pages dev

访问 http://localhost:8088 即可查看并调试应用。

安全与权限建议

  • 若对接口滥用有所顾虑，请启用 API_TOKEN 保护 /api/shorten 接口（客户端同源请求可仍可用）。
  • 如需更严格控制，可启用 PASSWORD 保护，在 UI 中要求用户输入密码创建短链。

结语

如果你需要一个简单、可扩展、低成本的短网址方案，基于 EdgeOne Pages + KV 的方法值得一试。项目代码已开源（https://github.com/lm379/dwz），欢迎 Fork、PR、Issue 与 Star！