TiddlyWiki 5.4.1 介绍与选型指南

目标：面向需要自建知识库的团队与个人，厘清 TiddlyWiki 的实体身份、单文件与 Node.js 服务端两种形态、核心能力边界，并与 Wiki.js、DokuWiki、MediaWiki、Otter Wiki 做量化选型对比。本文为认知篇，版本与社区数据均来自官方站点与仓库，查询日期统一为 2026-11-02；生产部署与命令实测见同专栏《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》与《TiddlyWiki 5.4.1 常用 CLI 命令详解》。

一、环境信息

• 文档类型：A1 介绍与选型指南（认知篇，不做本地部署实测）
• 版本核实日期：2026-11-02
• TiddlyWiki 主版本：5.4.1（官方 Releases 最新稳定版，2026-07-10 发布）
• 官方仓库：TiddlyWiki/TiddlyWiki5
• 官方网站：https://tiddlywiki.com/
• Node.js 运行要求：>=20.0.0（来自 npm 包 tiddlywiki@5.4.1 的 engines 字段）
• 参考生产系统：Ubuntu 24.04 LTS x86_64（服务端部署见《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》）
• 默认 HTTP 端口：8080；本文部署篇按规划使用 8138

💡 说明：本文只做事实核实与横向对比，不把任何“本机已跑通”的命令回显写进来。涉及部署的端口、systemd、备份与权限实测，全部放在《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》，避免认知篇与实操篇混淆。

二、软件概述

2.1 它是什么

TiddlyWiki 是一个用 JavaScript 实现的“非线性个人网络笔记本”（non-linear personal web notebook）。它把 Wiki 引擎本身和内容一起装进一个 HTML 文件：浏览器打开就是可编辑的 Wiki，保存时由浏览器下载一份新的 HTML 文件。这个形态从 2004 年延续至今，核心卖点是不依赖服务器、不依赖数据库、单文件即可长期保存。

官方仓库对它的定位写得很直接：TiddlyWiki 是一个完整的 JavaScript 交互式 Wiki，既可作为浏览器中的单个 HTML 文件使用，也可作为功能强大的 Node.js 应用运行；整个用户界面本身也是用可修改的 WikiText 实现的。

它和传统 Wiki 的最大区别在内容组织方式：传统 Wiki 以“页面”为单位，TiddlyWiki 以“Tiddler”为单位。一条 Tiddler 是一个原子化的小条目，可以是一条笔记、一个任务、一段代码、一张图片，甚至一个界面组件；页面只是 Tiddler 的排列结果，而不是固定页面。这种“先有原子条目、再动态组合页面”的思路，就是官方所说的“非线性”。

2.2 项目身份与许可证

• 创作者：Jeremy Ruston
• 版权归属：2004-2007 Jeremy Ruston；2007-2025 UnaMesa Association
• 许可证：BSD 3-Clause（宽松许可，允许修改、再分发、商用，不要求开源衍生作品）
• 官方许可证页：https://tiddlywiki.com/static/License.html
• 代码仓库：https://github.com/TiddlyWiki/TiddlyWiki5
• npm 包名：tiddlywiki，preferGlobal: true，安装后提供 tiddlywiki 命令

BSD 3-Clause 对自托管很友好：内部改造界面、二次分发、嵌入商业产品都不需要额外授权费；代价是官方不提供任何 warranty，数据安全与备份需要自己负责。

2.3 版本节奏与社区规模

截至 2026-11-02 的官方实查结果：

⚠️ 注意：npm registry 的 latest 标签在核查时仍可能返回旧版本号（本次查询 /latest 返回 5.3.3，但 5.4.1 的包元数据与 tarball 均存在，官方 Releases 也以 5.4.1 为最新）。部署时建议显式指定版本号 tiddlywiki@5.4.1，不要依赖浮动 latest，避免装到旧版。

三、核心架构

3.1 Tiddler：最小内容单元

一条 Tiddler 由“字段 + 正文”组成。常用字段包括：

Tiddler 的标题是全局唯一的。页面、侧边栏、标签视图都不是独立文件，而是用过滤器（Filter）从 Tiddler 集合中动态筛选出来的结果。因此同一批 Tiddler 可以同时出现在多个“页面”里，不需要复制内容。

3.2 单文件运行形态

单文件形态下，整个 Wiki（引擎 + 所有 Tiddler + 插件 + 主题）被序列化进一个 .html 文件。使用流程是：

1. 从官网下载空白单文件 Wiki（https://tiddlywiki.com/empty.html）；
2. 浏览器打开，直接新建/编辑 Tiddler；
3. 点击保存，浏览器下载一份包含最新内容的新 HTML 文件；
4. 用新文件覆盖旧文件，完成“保存”。

优点是没有服务端、没有数据库、拷贝一个文件就完成迁移和备份；缺点是多人不能同时编辑，保存依赖浏览器的文件下载行为，移动端体验受限，内容体积变大后单文件会变得笨重。

3.3 Node.js 服务端形态

Node.js 形态把 Tiddler 拆成独立文件存放在 Wiki 文件夹里，并由内置 HTTP 服务器对外提供访问。官方给出的主要收益是：

• Tiddler 单独存储，可按自己的规则组织目录；
• 可以构建多个 Wiki，共享一部分内容、保留各自独有的内容；
• 任何现代浏览器（包括手机和平板）都能编辑；
• 通过 --listen 启动 HTTP/HTTPS 服务，支持 Basic Auth、多用户凭据文件、读写权限列表。

服务端形态的存储结构大致如下：

/var/lib/tiddlywiki/wiki/
├── tiddlywiki.info        # Wiki 配置：插件、主题、语言、构建目标
├── tiddlers/              # 普通 Tiddler，一条一个 .tid 或 .json
├── plugins/               # 自定义插件（可选）
├── credentials.csv        # 多用户凭据（启用 credentials 参数时）
└── output/                # --build 生成的静态站点

server edition 初始化后，tiddlywiki.info 默认包含三个插件：tiddlywiki/tiddlyweb（服务端保存与同步）、tiddlywiki/filesystem（文件系统存储）、tiddlywiki/highlight（代码高亮），主题为 tiddlywiki/vanilla 与 tiddlywiki/snowwhite。

💡 技术拓展：Wiki 的存储模型不止一种。常见三类对比如下——

存储模型	代表产品	特点	适用场景
单文件内嵌	TiddlyWiki 单文件版	一个 HTML 包含全部内容，零依赖	个人笔记、离线分发、长期归档
扁平文件	TiddlyWiki Node 版、DokuWiki	一条/一页一个文件，可直接用 Git 管理	小团队、需要版本追踪、可接受文件级备份
关系型数据库	Wiki.js、MediaWiki	元数据与正文入库，支持复杂查询与大规模并发	中大型组织、强权限、多站点

本文讨论的 TiddlyWiki 服务端形态采用“扁平文件”模型：正文落 .tid/.json，索引在内存中构建，因此备份就是打包目录，迁移就是拷贝目录。

3.4 保存与同步机制

Node.js 服务端形态下，浏览器编辑通过 HTTP API 回写：

• 新建或更新 Tiddler：PUT /recipes/default/tiddlers/<title>；
• 读取单条：GET /recipes/default/tiddlers/<title>，请求头 Accept: application/json 返回 JSON；
• 删除：DELETE /bags/default/tiddlers/<title>；
• 列表：GET /recipes/default/tiddlers.json。

服务端收到写请求后，由 filesystem 插件把 Tiddler 落盘到 tiddlers/ 目录。官方明确提示：Node.js 形态不支持在服务运行期间直接修改 Tiddler 文件，文件系统层面的改动必须重启服务才能生效；与运行中的 Wiki 交互应走 HTTP API 或 JavaScript API。这一点对运维很关键：用 CLI 导入文件后，若服务没重启，浏览器里看不到新内容。

3.5 插件、主题与过滤器

TiddlyWiki 的 UI 本身就是 WikiText，因此“改界面”和“写内容”用的是同一套语言。扩展体系分三层：

• 插件（plugins）：增加功能，如 Markdown 解析、代码编辑器、图表、数学公式；
• 主题（themes）：改变外观与布局；
• 语言包（languages）：界面本地化。

官方插件库中的插件以 publisher/title 形式引用，例如 tiddlywiki/markdown。Node.js 形态安装官方插件的标准做法是编辑 tiddlywiki.info 的 plugins 数组，然后重启服务；不需要手工下载插件文件。自定义插件则放入 plugins/ 目录并在配置中引用。

过滤器（Filter）是 TiddlyWiki 的查询语言，形如 [!is[system]]、[tag[project]]、[title[MyTiddler]]。它既用于页面展示，也用于 CLI 的 --save、--render、--deletetiddlers 等命令。学会过滤器，等于掌握了 TiddlyWiki 的“SQL”。

四、功能特性

五、快速开始（官方最小路径）

💡 说明：本节命令取自官方文档与官方仓库说明，用于说明“最短上手路径”，不在认知篇重复做本地实测；完整安装、systemd 托管、备份与验证回显见同专栏《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》。

5.1 单文件最小使用

1. 打开 https://tiddlywiki.com/empty.html，浏览器会加载一个空白 Wiki；
2. 点击右侧“+”新建 Tiddler，输入标题与正文；
3. 点击保存按钮，浏览器下载一个新的 HTML 文件；
4. 用下载的新文件替换旧文件，即完成保存。

这个流程不需要 Node.js、不需要任何服务端进程，适合个人离线笔记。

5.2 Node.js 服务端最小使用

官方文档给出的最小命令序列是：

npm install -g tiddlywiki@5.4.1
tiddlywiki mywiki --init server
tiddlywiki mywiki --listen

三行命令分别完成：全局安装 CLI、用 server edition 初始化 mywiki 目录、在默认 127.0.0.1:8080 启动 HTTP 服务。浏览器访问 http://127.0.0.1:8080/ 即可编辑。若要允许局域网访问，需要显式指定 host=0.0.0.0；若要加登录，追加 username=admin password=q1w2e3r4。

六、适用场景与限制

6.1 适用场景

• 个人知识库与长期笔记：单文件形态最省心，一个 HTML 管一辈子，不依赖任何云服务。
• 小团队内部 Wiki：Node.js 形态 + readers=(anon) writers=admin,alice，几十人规模足够。
• 项目文档与手册：用 Tiddler 拆章节，用标签和过滤器组合出多个视图，再用 --build static 导出静态站。
• 需要 Git 管理的文档：一条 Tiddler 一个文件，diff 粒度细，适合随代码仓库一起版本化。
• 离线/内网分发：单文件 HTML 可以直接邮件、U 盘、内网下载分发。
• 高度定制界面：UI 本身就是 WikiText，改主题、改布局不需要写前端框架。

6.2 不适用场景

• 需要企业级 RBAC、审计、SSO 的组织：内置权限只有“读/写”两个维度和用户名列表，没有角色、组、细粒度页面权限。
• 大规模并发编辑：扁平文件 + 内存索引适合小团队；大量用户同时写入需要数据库型 Wiki。
• 必须提供 REST 开放平台的重型应用：TiddlyWiki 的 HTTP API 是 TiddlyWeb 风格的轻量接口，不是完整的现代 REST 平台。
• 不能接受“改文件要重启”的运维模式：CLI 导入或手工改 .tid 后必须重启服务才生效。

6.3 已知限制

• 内置认证面向可信网络：官方明确说明其多用户机制“简单易用，但通常不足以直接暴露在公网”，建议在前面加外部代理。
• 没有真正的并发冲突合并：同一 Tiddler 的并发保存以最后一次写入为准，服务端用 revision 计数，但不做三方合并。
• 运行期文件改动不生效：官方警告 Node.js 形态不支持运行中直接改 Tiddler 文件，必须重启。
• 单文件体积随内容增长：单文件形态把所有内容内嵌进 HTML，条目多、附件大时打开与保存都会变慢。
• 搜索是内存过滤：TiddlyWiki 的搜索基于内存中的 Tiddler 集合，不是全文检索引擎；超大规模内容不适合。
• 备份需要自己设计：官方不提供数据库式备份工具，需用目录打包或 Git 提交。

七、同类选型对比

7.1 量化对比表

下表数据均为 2026-11-02 实查官方 Releases、官方下载页与 GitHub 星标徽章所得；星标数为 shields.io 对相应仓库 stargazers 的取值，会随时间变化。

💡 解读：星标高不等于适合你。Wiki.js 的 29k 星标来自“现代 UI + 多站点 + 完整权限”的定位，代价是必须维护 PostgreSQL；MediaWiki 的 5.2k 星标背后是维基百科级生态，代价是 PHP + 数据库 + 较高的学习和运维成本；TiddlyWiki 的 8.7k 星标对应的是“零依赖、单文件、极致可定制”，代价是权限与并发能力有限。Otter Wiki 的 1.6k 星标代表轻量 Git 派，适合已经用 Git 管文档的团队。

7.2 单文件与服务端形态取舍

取舍建议很直接：如果你只是自己写笔记、需要“十年后还能打开”，选单文件；如果多人要通过浏览器访问、需要登录与写权限，选 Node.js 服务端。两者不是互斥的：服务端形态可以用 --build index 导出单文件 HTML 做归档，单文件也可以导入服务端继续协作。

7.3 选型建议

• 如果你要的是“一个文件、零依赖、长期保存” → TiddlyWiki 单文件版。
• 如果你要的是“小团队内网 Wiki、可登录、可写、部署简单” → TiddlyWiki Node.js 服务端；需要更强权限时再考虑 Wiki.js。
• 如果你必须用 PostgreSQL、需要多站点、完整用户组与外部认证 → Wiki.js。
• 如果你要的是“PHP 环境现成、无数据库、装完即用” → DokuWiki。
• 如果你要的是“维基百科式的大型公开站点、强扩展生态” → MediaWiki。
• 如果你的文档已经在 Git 里、想要一个轻量 Web 界面 → Otter Wiki。

八、参考链接

• TiddlyWiki 官网：https://tiddlywiki.com/
• TiddlyWiki 5.4.1 Releases：https://github.com/TiddlyWiki/TiddlyWiki5/releases/tag/v5.4.1
• TiddlyWiki 官方许可证说明：https://tiddlywiki.com/static/License.html
• TiddlyWiki on Node.js 官方说明：https://tiddlywiki.com/static/TiddlyWiki%20on%20Node.js.html
• TiddlyWiki --listen 命令参数：https://tiddlywiki.com/static/ListenCommand.html
• npm 包 tiddlywiki@5.4.1 元数据：https://registry.npmjs.org/tiddlywiki/5.4.1
• Wiki.js Releases：https://github.com/requarks/wiki/releases
• DokuWiki 版本变更记录：https://www.dokuwiki.org/changes
• MediaWiki 官方下载页：https://www.mediawiki.org/wiki/Download
• Otter Wiki Releases：https://github.com/redimp/otterwiki/releases
• GitHub 星标数据（shields.io）：https://img.shields.io/github/stars/TiddlyWiki/TiddlyWiki5.json、https://img.shields.io/github/stars/requarks/wiki.json、https://img.shields.io/github/stars/splitbrain/dokuwiki.json、https://img.shields.io/github/stars/wikimedia/mediawiki.json、https://img.shields.io/github/stars/redimp/otterwiki.json

数据查询日期：2026-11-02。版本号、星标、许可证可能随项目迭代变化，部署前请以官方最新页面为准。

同专栏文档：

• 《Ubuntu 24.04 安装 TiddlyWiki 5.4.1 并启用 Node 服务端模式指南》
• 《TiddlyWiki 5.4.1 配置参数详解》
• 《TiddlyWiki 5.4.1 常用 CLI 命令详解》