一、它是什么，解决什么问题

入门

微信群聊的二维码有个烦人的特点：过几天就失效，或者被换新的。你打印在海报上、放在宣传单里、发在公众号文章里的那张图，过一阵子就扫不出来了。

serverless-qrcode-hub 的思路很巧：二维码图片本身会过期，但指向它的链接可以永久有效。你把链接（比如 你的域名/join）印出去，微信群换了新二维码，你只需登录后台把图片换掉，同一个链接就指向新图了，之前印出去的所有地方都不用改。

它还有两个附带好处：

• 不用买服务器：整个工具跑在 Cloudflare Workers（一种让你的代码运行在 Cloudflare 全球网络上、按用量免费的托管服务）上，数据存在 Cloudflare 的 D1（同家公司的免费云端数据库）里，个人使用完全免费。
• 顺便是个短链接生成器：同一个后台也能把长网址压缩成短链，直接跳转。

二、开始前需要准备什么

入门

这个项目不需要在自己电脑上装任何东西，也不需要写代码，所有操作都在浏览器里完成。你只需要：

• 一个 Cloudflare 账号：去 cloudflare.com 免费注册，需要一个邮箱。
• 一个 GitHub 账号：去 github.com 免费注册，用来复制项目源码（Fork，意思是"把别人的仓库复制一份到自己名下"，这样你就能随意修改和部署）。
• （可选）一个自己托管在 Cloudflare 的域名：没有也能用，只是默认的 *.workers.dev 域名国内访问会偏慢，绑定自有域名会快不少。域名不是必须的。

如果你完全没接触过 GitHub，别被吓到：这一步你只需要点两次按钮，没有命令行、没有代码编辑器。

三、创建数据库：拿到数据库 ID

入门

先登录 Cloudflare 控制台，我们要建一个用来存二维码和短链数据的地方。

1. 在左侧菜单找到 Workers 和 Pages → D1 SQL 数据库，点击创建。
2. 数据库名字随便起，比如 qrcode，创建完成后进入详情页。
3. 在详情页顶部找到 数据库 ID，点击复制按钮把它拷下来。

这个 ID 是后面把代码和数据库"接上线"的凭据，先粘贴到记事本里存好，第五步要用。

四、复制项目到你自己的 GitHub

入门

打开项目仓库 github.com/xxnuo/serverless-qrcode-hub，登录你的 GitHub 账号，点击右上角的 Fork 按钮，再点 Create fork。几秒钟后，你的账号下就多了一份完全相同的代码。

接着改一个配置文件：

1. 进入你 Fork 后的仓库，找到 wrangler.toml 这个文件（这是 Cloudflare 的部署配置文件，记录着"这个服务要连哪个数据库"）。
2. 点击文件内容右上角的铅笔图标进入编辑模式。
3. 找到 d1_databases 下面的 database_id，把引号里的内容整段替换成刚才复制的 D1 数据库 ID。
4. 点击右上角 Commit changes（提交修改）保存。

提交时会让你填一段说明，什么都不填直接点确认也行。这一步只是改配置，不涉及任何代码逻辑。

五、一键部署到 Cloudflare

入门

回到 Cloudflare 控制台，进入 Workers 和 Pages，点击创建，选择 Pages（或 Worker，视界面版本而定），然后选择 连接到 Git。首次连接会要求你授权 GitHub——同意后选中你刚 Fork 的那个仓库。

部署设置页面上所有选项保持默认即可，直接点右下角的 保存并部署。等待片刻，部署成功后页面会自动跳转，你会看到一个 xxx.pages.dev 或 xxx.workers.dev 的临时网址，这就是你的工具地址了。

如果部署失败，最常见的原因是第四步的数据库 ID 没替换成功，回到 wrangler.toml 检查一遍再重新部署。

六、绑定自己的域名（推荐）

进阶 · 推荐细读

默认分配的域名在国内访问速度一般。如果你在 Cloudflare 托管了域名，建议绑一个子域名上来，访问快、也好记。

在部署好的项目页面里找到自定义域 / 域和路由设置，点击添加自定义域，输入一个子域名，比如：

qr.你的域名.com

注意这个域名必须是已经托管在你 Cloudflare 账号下的，否则绑定会失败。添加完成后 DNS 生效一般只需几分钟。如果你没有域名，跳过这一步也能正常使用。

七、设置访问密码

进阶 · 推荐细读

这个后台管着你的二维码，必须设密码，否则任何人都能进去改图。在 Cloudflare 项目的 设置 → 环境变量 中添加一个变量来作为登录密码，设置后需要重新部署一次才会生效。

密码要求是纯英文字母和数字，建议按 README 的推荐做法，用两段随机 UUID（一串由字母和数字组成的随机字符串）拼起来当密码，足够长也足够难猜。

密码别只存在浏览器里，建议同时记在密码管理器中。设置后建议立刻用无痕窗口访问一次，确认能正常登录。

八、核心用法：创建永久二维码和短链

入门

用你绑定的域名或默认地址打开工具，输入密码登录，就能看到管理后台。这里可以做两件事。

创建微信群二维码：点击添加，选择"微信二维码"类型，给它起个名字（比如"合作群"），设置一个短路径（比如 join），然后上传微信群二维码图片。你可以自定义二维码的样式和中间的 Logo，让它看起来更像官方物料。生成后你会得到一个类似 你的域名/join 的永久链接，把这个链接生成二维码图片下载下来，打印、发文章、做海报随便用。

创建普通短链：同一个后台选"短链"类型，填入长网址和短路径即可，访问时直接 301 跳转，适合分享带一大串参数的推广链接。

以后微信群换了新二维码，你只需要登录后台编辑那条记录、换一张图，链接和二维码地址完全不变，之前印出去的所有物料继续有效。

九、常见踩坑

进阶 · 推荐细读

部署完打不开或 500：多半是 wrangler.toml 里的数据库 ID 填错，或者数据库被删了。回到第四步核对 ID，确认 D1 数据库还在。

改了密码不生效：Cloudflare 的环境变量需要重新部署才会写入运行中的服务，改完去项目页面手动点一次 重新部署。

默认域名访问慢：*.workers.dev / *.pages.dev 在国内速度不稳定，这就是第六步建议绑域名的原因。

二维码扫不出来：检查上传的图片是否清晰、边缘留白是否足够。建议原图直接上传，不要截图再截图，压缩会明显降低识别率。

用了旧版本：早期版本用 KV（另一种存储）存储，免费额度太小，最后版本是 v1.2.0。如果你部署过旧版，建议按仓库里的迁移指南换到当前的 D1 版本。

十、判断建议

入门

这个工具适合这样的你：运营社群、做地推、印物料，需要一个不会失效的入群入口，又不想为一个二维码功能去买服务器、配环境。

它的优势是全程零成本、零运维：数据在 Cloudflare 免费额度内（D1 每月 500 万次读取），个人和小团队基本用不完。短板也很明显——所有功能都在一个密码后面，只适合单人管理；二维码图片存在 Cloudflare 的库里，别拿来存敏感资料。

如果你只是想做个短链服务，或者想给自己社群一个"换图不换链"的入口，按上面的步骤走一遍，10 分钟就能上线。

项目信息

参考链接

• GitHub 仓库

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「Python」中文使用教程
• 「AI_NovelGenerator」中文使用教程
• 「snipe-it」中文使用教程