BlogBookstore：把博客变成一间可以走进去的 3D 书店

如果博客文章不是一串列表，而是一本本摆在书架上的书，会是什么样子？

我做了一个网页项目 BlogBookstore：访客可以在街角调整时间和天气，走进两层书店，从馆藏目录或书架拿起文章阅读。二楼有休息区和小卖部，场景里的音乐、日落、云、雨雪和灯光也可以调整。

这个项目通过公开 RSS / Atom 接入博客。它可以作为独立网站部署，也提供一个可选的 Typecho 插件。

• 项目源码：LLLimit / BlogBookstore
• 下载发布包：GitHub Releases
• 作者：LLLimit
• 许可证：MIT，允许修改和分发，保留版权和许可证文本。

它能做什么？

• 可漫游的两层 3D 书店，博客文章显示为可阅读的书。
• 馆藏目录、文章搜索、正文阅读和原文链接。
• 昼夜流转、日落、移动云团、雨雪和雾。
• 音乐播放器、内置原创循环音乐，以及本机音频。
• 电脑 WASD 移动、鼠标环顾，手机使用摇杆与拖动视角。
• 浏览器保存阅读位置与字号。
• 设置后台可以修改书店名称、品牌缩写、封面作者、图标、RSS、缓存时间和默认场景。
• 支持订阅预览、手动更新、配置导出和管理员密码修改。

3D 渲染发生在访客浏览器中。独立部署时，服务器主要提供静态文件、PHP 设置后台和缓存后的 RSS，无需数据库或常驻 Node.js 服务。实际资源消耗仍取决于访客数量与使用环境。

我已经用自己的博客 RSS 做了实际接入测试：当时订阅返回 9 篇文章，后台保存、重新登录、缓存更新、馆藏目录和正文阅读都正常。RSS 返回多少历史文章、正文是否完整，取决于博客自身的订阅设置。

选择哪一个发布包？

三个包都以 BlogBookstore 为顶层目录。普通独立部署请选择 standalone 包，无需先安装 Node.js。

方式一：部署成独立网站

1. 准备运行环境

准备一个域名或子域名、网站目录，以及支持 PHP 的 Nginx / Apache 网站。使用宝塔等面板时，创建 PHP 网站即可。

需要启用：

• PHP，代码最低兼容 7.4；新部署请选择仍受官方支持的版本。
• cURL 扩展，用于获取 RSS。
• DOM / XML 扩展，用于读取和检查订阅。
• HTTPS，配置网站证书。

2. 上传文件

解压 standalone 包，把 BlogBookstore 文件夹内部的全部内容上传到网站根目录。

上传后，根目录应直接包含：

index.html
assets/
admin/
api/
config.json
favicon.svg
feed.xml
feed-meta.json

网站首页使用 index.html。这是独立项目，不需要套用 Typecho 的伪静态规则。也可以放在 /bookstore/ 等子目录。

PHP 运行用户需要能创建和写入 .bookstore 数据目录；其余源码只需读取。可以在面板里预建目录并设置正确的所有者，不需要把整个网站权限设成 777。

3. 初始化后台

打开：

https://你的书店域名/admin/index.php

如果部署到子目录，后台地址相应变成 /bookstore/admin/index.php。

首次打开后，使用服务器文件管理器查看网站根目录里的：

.bookstore/install-key.php

复制其中 key 的值，填写到后台安装码输入框，再设置管理员密码。密码需要 12–72 字节，建议使用至少 12 个 ASCII 字符组成的长密码。

安装码不会通过网页公开提供。成功初始化后，安装码文件会自动删除，后续使用管理员密码登录。

4. 接入博客 RSS

后台填写以下设置：

填写的是 订阅地址，不是博客首页。应优先使用博客页面上提供的 RSS 链接。

本站实际测试使用的地址是：

https://blog.darkduck.fun/index.php/feed/

不同 Typecho 站点的地址会随伪静态等配置变化，请以自己的订阅入口为准。WordPress、Hexo、Hugo、Astro 等也可以使用各自公开的 RSS / Atom。

点击“测试当前订阅”，后台会显示订阅标题、文章数量和前五篇预览。确认后点击“保存设置”，再刷新书店，文章就会自动上架。

5. 更新与维护

缓存期间，访客复用同一份 RSS。博客更新后，缓存到期会重新获取；也可以在后台点击“立即更新已保存的 RSS”。

单份 RSS 上限为 4 MB，前端最多展示 1000 篇文章，实体书架每批展示 24 本。RSS 的历史篇数由上游博客决定，不能通过这个项目自动获得订阅之外的全部文章。

设置、密码哈希和缓存保存在 .bookstore。升级前备份该目录，覆盖其他发布文件时保留它；迁移时一起复制网站文件和数据目录。

忘记管理员密码时，在服务器网站根目录的终端执行：

php api/reset-admin.php

按提示输入新密码。这个工具只允许在服务器终端运行，旧登录会失效。

方式二：作为 Typecho 插件运行

如果希望直接读取本站公开文章，并使用 Typecho 原有插件设置，可以下载插件包。

把完整的 BlogBookstore 文件夹上传到：

usr/plugins/BlogBookstore/

确保这个文件存在：

usr/plugins/BlogBookstore/Plugin.php

文件夹名称必须严格为 BlogBookstore，大小写也要一致。不要将安装目录改成发布压缩包的文件名。

在 Typecho 后台启用插件，设置书店名称和默认封面作者，再点击“打开 3D 书店”。插件直接读取本站文章，支持分页；草稿、私密、密码保护和未来发布的文章不会公开。

Typecho 模式使用插件设置；独立 RSS 模式使用 /admin/index.php，两种方式按自己的部署需要选择。

本地开发与修改

源码开发需要 Node.js 22.12 或更新版本、pnpm，以及 PHP、cURL、DOM / XML。

git clone https://github.com/LLLimit/BlogBookstore.git
cd BlogBookstore
pnpm install
pnpm dev

默认前台与后台地址：

http://127.0.0.1:8795/
http://127.0.0.1:8795/admin/index.php

Vite 会启动本机 PHP 后台。PHP 不在 PATH 时，把 .env.example 复制成 .env，填写 BOOKSTORE_PHP_BIN 为 PHP 程序的绝对路径，再启动。

本地安装码与数据默认放在 .local/data，不进入 Git 和发布包。Windows 也可以双击源码目录里的“启动书店.cmd”。

构建与打包：

pnpm build
pnpm package

dist 是部署目录，releases 会生成三个发布包。

GitHub Pages 能部署吗？

可以部署纯静态书店，但 GitHub Pages 不执行 PHP，无法提供服务器设置后台。

使用纯静态方式时：

1. 修改 public/config.json，填写自己的书店名称、博客首页和 feedUrl，将 feedEndpoint 设为空字符串。
2. 执行 pnpm sync 获取订阅快照。
3. 执行 pnpm build，发布 dist。
4. 以后更新文章时，重新同步和构建，或更新部署后的 feed.xml 与 feed-meta.json。

希望在网页后台直接更换 RSS 和外观设置时，请使用支持 PHP 的独立网站。

常见问题

能把所有旧文章都上架吗？

独立 RSS 模式只能读取订阅中提供的内容。可以调整博客的 RSS 输出范围；Typecho 插件模式可以直接分页读取本站公开文章。

为什么有些文章只有摘要？

博客可能只输出摘要订阅。书店会展示 RSS 提供的内容，并保留“在博客中阅读原文”入口。想显示完整正文，需要博客自身提供全文 RSS。

提示 RSS 不能来自本机或内网地址？

后台只接受公网 HTTP / HTTPS 订阅，端口为 80 / 443。部分本机代理使用 Fake-IP，会把公网域名解析成 198.18.x.x，也会触发拦截。

这种情况可以为指定域名配置 BOOKSTORE_DNS_OVERRIDES，填写真实公网 IP，并重启服务。使用方法见项目 README；真实 IP 变化后需要更新。公网地址校验和 HTTPS 证书验证仍然保留。

内置浏览器提示无法锁定鼠标？

部分内置浏览器限制鼠标锁定。可以把书店地址复制到 Chrome 或 Edge 里打开。馆藏目录和正文阅读可独立使用。

浏览器保存的阅读位置会同步到账号吗？

不会。当前阅读位置和字号保存在当前浏览器，清除站点数据会删除记录。

正文会经过 DOMPurify 清理，不执行脚本、iframe 或表单；图片从原站加载。请使用有权展示的公开订阅内容。

欢迎体验、修改和分享这个项目。源码和安装包都在 BlogBookstore GitHub 仓库 中。