第四课 用 AI 开发 Trilium WP 进行知识展示

在内容管理与知识管理日益融合的今天，如何将个人知识库无缝嵌入到公开网站中，成为了许多内容创作者、技术团队和知识工作者面临的核心课题。Trilium Notes 是一款功能强大的开源层级化笔记应用，WordPress 是全球使用最广泛的内容管理系统，而 Trilium WP 插件则是连接这两个世界的桥梁——它通过 Trilium 的 ETAPI 接口，将你在 Trilium 中精心组织的笔记、知识库、文档体系，完整地呈现在 WordPress 站点上。

本节课程分为两大部分。第一部分聚焦于插件开发的底层逻辑，帮助你理解"这样一个插件是如何被构建出来的"，需要掌握哪些基础知识和开发技能；第二部分则是详尽的使用教程，手把手教你从安装配置到高级功能的全流程操作。无论你是希望深入学习 WordPress 插件开发的技术人员，还是只想高效使用这个工具的内容管理者，都能在本课程中找到所需的知识。

第一部分：插件开发原理与基础知识

一、WordPress 插件开发概述

1.1 什么是 WordPress 插件

WordPress 插件是一种遵循 WordPress 标准编写的 PHP 程序包，它能够在不修改 WordPress 核心代码的前提下，为网站扩展功能。每一个插件本质上是一个独立的功能模块，WordPress 通过其内置的钩子系统（Hooks System）与插件进行交互。

插件的工作方式可以形象地理解为"挂钩"：WordPress 在执行各种操作（如加载页面、保存文章、渲染菜单）时，会在特定节点广播信号，插件通过"挂钩"到这些信号上来执行自己的逻辑。这种机制保证了系统的可扩展性和模块化。

📌 核心概念速览：

• 动作钩子（Action Hooks）：在 WordPress 执行某个操作时触发，插件可以在此时点"插入"自己的代码来执行额外任务。例如 init 钩子在 WordPress 初始化完成后触发，wp_enqueue_scripts 钩子在前端页面加载脚本时触发。
• 过滤器钩子（Filter Hooks）：与动作钩子不同，过滤器钩子用于"修改"数据。WordPress 将数据传递给挂钩的函数，函数处理后返回修改过的数据。例如 the_content 过滤器允许你在文章内容输出前对其进行加工。
• 短代码（Shortcodes）：一种特殊的标记语法，形如 [shortcode_name param="value"]，用户可以在文章或页面编辑器中插入它，WordPress 会在渲染时将其替换为插件生成的 HTML 内容。

1.2 开发 Trilium WP 这类插件需要的知识储备

要开发一个像 Trilium WP 这样涉及外部 API 集成、前后端交互、内容处理的中等复杂度插件，你需要具备以下几个层面的知识：

第一层：编程语言基础

• PHP（必备，核心语言）：WordPress 本身是用 PHP 编写的，插件开发的主体代码也是 PHP。你需要熟练掌握 PHP 的面向对象编程、数组操作、字符串处理、HTTP 请求（wp_remote_get / wp_remote_post）等技能。Trilium WP 的所有后端逻辑——API 调用、数据处理、短代码注册、管理后台渲染——全部由 PHP 完成。
• JavaScript（必备，交互层）：前端的动态交互依赖 JavaScript。Trilium WP 使用了三个独立的 JS 文件分别处理管理后台交互、前端浏览器组件和知识库导航树。你需要掌握 DOM 操作、事件监听、AJAX 异步请求、以及 JSON 数据处理。
• HTML 与 CSS（必备，展示层）：所有的前端呈现最终都是 HTML 和 CSS。Trilium WP 包含超过 3000 行的 CSS 代码，涵盖响应式布局、暗色模式适配、打印样式优化等。

第二层：WordPress 专属知识

• 插件 API：包括钩子系统（add_action、add_filter）、短代码 API（add_shortcode）、设置 API（register_setting、add_settings_section）、选项 API（get_option、update_option）等。
• AJAX 机制：WordPress 有自己独特的 AJAX 处理方式，通过 wp_ajax_ 和 wp_ajax_nopriv_ 前缀的动作钩子来区分已登录和未登录用户的 AJAX 请求。Trilium WP 注册了多个 AJAX 端点用于笔记搜索、内容获取、图片代理等功能。
• 安全机制：Nonce 验证（防止跨站请求伪造）、权限检查（current_user_can）、数据消毒（sanitize_text_field）、输出转义（esc_html、esc_attr、esc_url）——这些是 WordPress 插件开发中不可忽视的安全实践。
• 缓存系统：WordPress 的 Transients API 提供了带过期时间的临时数据存储机制，Trilium WP 利用它来缓存 API 响应结果，避免每次页面加载都向 Trilium 服务器发起请求。

第三层：外部集成知识

• RESTful API 原理：理解 HTTP 方法（GET/POST/PUT/DELETE/PATCH）、请求头、响应状态码、JSON 数据格式等。Trilium WP 与 Trilium Notes 服务器通过 ETAPI（一套 RESTful 风格的 API）通信。
• 认证与安全传输：ETAPI Token 认证、HTTPS/SSL 证书验证等。

第四层：前端工程能力

• 响应式设计：媒体查询（Media Queries）、弹性布局（Flexbox/Grid）、移动优先设计理念。
• CSS 架构：如何组织大规模样式表，如何处理主题兼容性（Trilium WP 特别针对 BuddyBoss 主题做了适配）。
• 无障碍访问（Accessibility）：ARIA 属性、键盘导航支持、语义化 HTML。

1.3 Trilium WP 的整体架构

📐 了解一个插件的架构，有助于你理解它的设计思路和代码组织方式。Trilium WP 采用了清晰的目录分层结构：

trilium-wp/
├── trilium-wp.php          ← 插件入口文件（注册钩子、加载资源）
├── admin/                  ← 管理后台页面
│   ├── admin-main.php      ← 仪表盘/欢迎页
│   ├── admin-settings.php  ← 设置表单
│   └── admin-browse.php    ← 笔记浏览器
├── assets/                 ← 静态资源
│   ├── css/
│   │   ├── trilium-styles.css     ← 主 UI 样式
│   │   └── trilium-content.css    ← 笔记内容样式
│   └── js/
│       ├── trilium-admin.js       ← 管理后台交互
│       ├── trilium-frontend.js    ← 前端浏览组件
│       └── trilium-kb.js          ← 知识库导航系统
└── includes/               ← 核心功能模块
    ├── admin-menu.php      ← 管理菜单注册
    ├── ajax.php            ← AJAX 请求处理器
    ├── api.php             ← Trilium ETAPI 封装
    ├── image-proxy.php     ← 图片/PDF 代理
    ├── kb.php              ← 知识库树形结构逻辑
    ├── processors.php      ← 内容类型处理器
    ├── settings.php        ← 设置读写逻辑
    ├── shortcodes.php      ← 短代码定义
    └── utilities.php       ← 缓存管理、激活/停用

这种分层体现了关注点分离（Separation of Concerns）的设计原则：

• 🏗️ trilium-wp.php 作为入口，只负责"初始化"——注册钩子、引入依赖文件、加载资源
• 🏗️ admin/ 目录负责所有管理后台的"视图"渲染
• 🏗️ includes/ 目录负责所有"业务逻辑"——API 通信、数据处理、功能注册
• 🏗️ assets/ 目录负责所有"静态资源"——样式和脚本

二、插件核心模块解析

2.1 插件入口文件

每个 WordPress 插件都有一个入口文件，它包含一个特殊格式的文件头注释，WordPress 通过解析这个注释来识别插件的基本信息：

/**
 * Plugin Name: Trilium WP
 * Description: 将Trilium笔记集成到WordPress
 * Version: 1.6.0
 * Author: satoshi
 */

入口文件的职责是"统筹全局"。Trilium WP 的入口文件 trilium-wp.php 主要完成以下工作：

📎 定义常量：将插件的版本号、文件路径、目录路径等定义为 PHP 常量，方便在其他文件中引用。

📎 引入功能模块：通过 require_once 加载 includes/ 目录下的所有核心文件，将各个功能模块"激活"。

📎 注册前端资源：通过 wp_enqueue_scripts 钩子注册 CSS 和 JavaScript 文件，确保它们在前端页面正确加载。这里有一个值得注意的细节——Trilium WP 使用文件修改时间（filemtime）作为版本号参数，这是一种常用的缓存刷新策略，确保用户在插件更新后能立即加载最新的资源文件。

📎 注册激活/停用钩子：通过 register_activation_hook 和 register_deactivation_hook 分别注册插件激活时和停用时需要执行的操作——在这个插件中，主要是缓存的初始化和清理。

2.2 API 通信层

includes/api.php 是 Trilium WP 最核心的文件之一，它封装了与 Trilium Notes 服务器的所有通信逻辑。这个文件可以看作是一个"翻译官"，将 WordPress 的请求转化为 Trilium ETAPI 能理解的格式，再将 ETAPI 的响应翻译回 WordPress 能使用的数据。

🔧 读取类函数（GET 请求）：

🔧 写入类函数（POST/PUT/PATCH/DELETE 请求）：

这是 v2.0.0 预留的高级功能，包括创建笔记（trilium_create_note）、更新笔记标题和内容（trilium_update_note）、删除笔记（trilium_delete_note）、克隆笔记（trilium_clone_note）以及添加属性（trilium_add_attribute）。

每个 API 请求都遵循相同的模式：构建请求 URL → 设置请求头（含 ETAPI Token） → 发送 HTTP 请求 → 检查响应状态 → 解码 JSON 数据 → 缓存结果 → 返回数据。这种统一的模式让代码具有很好的可维护性。

2.3 短代码系统

includes/shortcodes.php 是整个插件中代码量最大的文件（1125 行），它定义了六个短代码，每个短代码本质上是一个 PHP 函数，接收用户传入的参数，执行相应的逻辑，最后返回 HTML 字符串。

短代码的工作流程可以概括为：

用户在编辑器中输入 [trilium_note id="abc123"]
         ↓
WordPress 解析到短代码标签
         ↓
调用注册的回调函数 trilium_note_shortcode()
         ↓
函数向 Trilium API 请求笔记数据
         ↓
经过内容处理器格式化后，返回 HTML
         ↓
WordPress 将 HTML 替换掉原始短代码标签
         ↓
用户看到渲染后的笔记内容

六个短代码各有侧重，我们将在第二部分逐一详细讲解其使用方法。

2.4 内容处理器

includes/processors.php 体现了**策略模式（Strategy Pattern）**的设计思想。Trilium Notes 支持多种笔记类型（文本、代码、图片、PDF、搜索、关系图等），每种类型的内容需要不同的渲染方式。内容处理器为每种类型定义了独立的处理函数：

• 📝 文本笔记（text）：直接输出 HTML 内容，因为 Trilium 的文本笔记本身就以 HTML 格式存储
• 💻 代码笔记（code）：将代码包裹在 <pre><code> 标签中，并根据 MIME 类型映射到对应的编程语言标识，支持语法高亮
• 🖼️ 图片笔记（image）：通过 WordPress AJAX 代理机制加载图片，避免直接暴露 Trilium 服务器地址
• 📄 PDF 笔记（file）：生成下载按钮和内联预览链接
• 🔍 搜索笔记、关系图笔记等：显示友好的提示信息，说明该类型笔记的用途

2.5 图片代理机制

这是一个容易被忽略但非常重要的模块。Trilium Notes 中的图片引用使用的是相对路径（如 api/images/xxx/filename），这些路径在 Trilium 的 Web 界面中可以正常工作，但在 WordPress 页面中会因为域名不同而无法加载。

includes/image-proxy.php 的解决方案分为两步：

🔄 服务端重写：在 PHP 层面，用正则表达式扫描笔记内容中的所有 src 属性，将 Trilium 的相对路径替换为 WordPress 的 AJAX 代理 URL。

🔄 客户端监听：使用 JavaScript 的 MutationObserver API 监视 DOM 变化，当页面动态加载新内容时，实时修正其中的图片路径。这种双重保障确保了无论图片是在初始渲染还是后续动态加载中出现，都能正确显示。

2.6 知识库导航系统

知识库（Knowledge Base）是 Trilium WP 最复杂的功能模块，它涉及后端的 includes/kb.php 和前端的 assets/js/trilium-kb.js，两者协同工作，构建了一个完整的树形导航体验。

⚙️ 后端优化——单次 API 调用加载全树：

朴素的实现方式是为每个节点分别调用 API 获取其子节点，这会导致所谓的N+1 查询问题——如果树有 100 个节点，就需要 101 次 API 调用。Trilium WP 采用了更高效的方案：通过一次 API 搜索调用获取根节点下的所有后代笔记，然后在 PHP 内存中根据父子关系组装树形结构。这将网络请求次数从 N+1 降低到了 1。

⚙️ 前端交互——懒加载与状态管理：

前端 JavaScript 实现了完整的树形导航交互，包括：节点展开/折叠、面包屑导航、搜索过滤、最近更新列表、侧边栏显示/隐藏状态的持久化等。

2.7 缓存管理

includes/utilities.php 实现了基于 WordPress Transients API 的多层缓存策略：

• 🗃️ 笔记内容缓存：对每篇笔记的元数据和内容分别缓存，缓存键使用 trilium_note_{id} 和 trilium_content_{id} 的格式
• 🗃️ 搜索结果缓存：对搜索查询结果进行缓存，避免重复搜索产生不必要的 API 调用
• 🗃️ 树形结构缓存：知识库的完整树形数据也被缓存，大幅提升知识库页面的加载速度
• 🗃️ 缓存版本控制：通过 trilium_cache_version 选项实现选择性缓存失效——当你需要刷新数据时，只需递增版本号，所有相关缓存会自动过期
• 🗃️ 精确清理：支持按单个笔记 ID 清除缓存，也支持一键清除所有 Trilium 相关缓存

2.8 安全机制

安全是 WordPress 插件开发中最不容忽视的环节。Trilium WP 在多个层面实施了安全防护：

🛡️ Nonce 验证：所有 AJAX 请求都需要携带 WordPress 生成的 Nonce（Number Used Once）令牌，服务端验证此令牌以防止 CSRF（跨站请求伪造）攻击。

🛡️ 权限检查：通过 current_user_can() 函数检查当前用户是否具备执行某操作的权限。例如，管理后台的设置页面要求用户具有 manage_options 能力，前端浏览功能可以配置为仅限管理员、文章作者或所有访客访问。

🛡️ 输入消毒与输出转义：所有用户输入在使用前都经过 sanitize_text_field() 处理，所有输出到 HTML 中的数据都经过 esc_html()、esc_attr() 或 esc_url() 转义，防止 XSS（跨站脚本）攻击。

🛡️ API Token 保护：Trilium ETAPI Token 存储在 WordPress 数据库的 options 表中，前端代码无法直接访问，所有 API 通信都通过服务端中转。

三、开发此类插件的实践建议

3.1 开发环境搭建

在开始编写代码之前，你需要一个本地开发环境。推荐的工具组合如下：

• 🖥️ 本地 WordPress 环境：推荐使用 LocalWP 或 Docker Compose 快速搭建，它们可以在几分钟内创建一个包含 Apache/Nginx + PHP + MySQL 的完整 WordPress 运行环境
• 🖥️ Trilium Notes 服务器：可以在本地运行 Trilium Desktop 版本（自带 Web 服务器功能），或使用 Docker 部署 Trilium Server
• 🖥️ 代码编辑器：推荐 VS Code，配合 PHP Intelephense 扩展、WordPress Snippets 扩展、ESLint 等
• 🖥️ 调试工具：浏览器开发者工具（F12）用于前端调试，error_log() 函数或 Query Monitor 插件用于 PHP 调试

3.2 开发工作流程

一个典型的 WordPress 插件开发工作流程如下：

1. ✏️ 明确需求：确定插件要解决什么问题，列出核心功能清单
2. ✏️ 设计架构：确定文件结构、模块划分、数据流向
3. ✏️ 搭建骨架：创建入口文件，注册基本钩子，确认插件能被 WordPress 识别和激活
4. ✏️ 逐模块开发：按优先级依次开发各功能模块，每完成一个模块就进行测试
5. ✏️ 样式完善：在功能稳定后，投入精力优化 UI 和交互体验
6. ✏️ 安全审计：检查所有用户输入是否被消毒，所有输出是否被转义，所有 AJAX 请求是否有 Nonce 验证
7. ✏️ 性能优化：加入缓存机制、减少不必要的 API 调用、优化 SQL 查询
8. ✏️ 测试与发布：在不同主题、不同 PHP 版本、不同浏览器下进行兼容性测试

3.3 常见陷阱与注意事项

🚧 避免直接操作数据库：除非有特殊需求，否则应始终使用 WordPress 提供的 API 函数（如 get_option、update_option、get_transient 等），而非直接编写 SQL。

🚧 处理 API 超时：与外部服务通信时，网络超时是不可避免的。Trilium WP 设置了可配置的超时时间（默认 30 秒），并在 API 调用失败时返回友好的错误信息而非直接崩溃。

🚧 兼容性考量：不同的 WordPress 主题可能有截然不同的 CSS 样式，你的插件输出的 HTML 可能会被主题样式意外影响。Trilium WP 通过使用高度特异性的 CSS 选择器和 BuddyBoss 专属适配来应对这一问题。

🚧 国际化与本地化：虽然当前版本的 Trilium WP 界面文本全部使用中文硬编码，但最佳实践是使用 WordPress 的国际化函数（__() 和 _e()）包裹所有可见文本，并提供 .pot 翻译模板文件，以便未来支持多语言。

第二部分：Trilium WP 插件使用教程

四、安装与基础配置

4.1 前置条件

在安装 Trilium WP 之前，请确保你已经具备以下条件：

✅ 一个运行中的 WordPress 网站

• WordPress 版本建议 5.0 或以上
• PHP 版本建议 7.4 或以上
• 你拥有该网站的管理员权限

✅ 一个可访问的 Trilium Notes 服务器

• 可以是本地部署的 Trilium Desktop（默认端口 37840）
• 也可以是通过 Docker 或 VPS 部署的 Trilium Server
• 服务器需要能被 WordPress 所在的服务器通过网络访问到（如果两者不在同一台机器上）

✅ Trilium ETAPI Token

• 在 Trilium Notes 中，进入 菜单 → 选项 → ETAPI
• 点击"创建新的 ETAPI Token"
• 妥善保存生成的 Token 字符串，后续配置需要用到

4.2 安装插件

Trilium WP 的安装与其他 WordPress 插件完全一致，提供两种安装方式：

方式一：通过 WordPress 后台上传安装

1. 📦 登录 WordPress 管理后台
2. 📦 进入 插件 → 安装插件 → 上传插件
3. 📦 点击"选择文件"，选中 trilium-wp-1.6.0.zip 压缩包
4. 📦 点击"现在安装"，等待安装完成
5. 📦 点击"启用插件"

方式二：通过 FTP/文件管理器手动安装

1. 📦 将 trilium-wp-1.6.0.zip 解压，得到 trilium-wp 文件夹
2. 📦 将整个 trilium-wp 文件夹上传到 WordPress 安装目录下的 wp-content/plugins/ 目录
3. 📦 进入 WordPress 管理后台 插件 页面
4. 📦 在插件列表中找到 "Trilium WP"，点击"启用"

安装成功后，你会在 WordPress 管理后台的左侧菜单栏看到一个新增的 "Trilium Notes" 菜单项。

4.3 配置连接参数

安装并启用插件后，第一步是配置与 Trilium 服务器的连接。进入 Trilium Notes → 设置 页面，你会看到以下配置项：

基本连接设置

📌 关于 API 地址的格式说明：地址应以 /etapi 结尾，不要包含末尾的斜杠。如果你的 Trilium 部署在子路径下，请确保路径完整，例如 https://example.com/trilium/etapi。

高级设置

⚠️ SSL 验证说明：如果你的 Trilium 服务器使用自签名证书，可能需要临时关闭 SSL 验证才能成功连接。但在生产环境中，强烈建议使用受信任的 SSL 证书并保持此选项开启。

⚠️ 前端访问权限说明：此设置控制的是"前端浏览/搜索功能"的访问权限，不影响通过短代码嵌入的笔记内容的可见性。嵌入的笔记内容对所有页面访客可见。三个权限级别分别为：

• 👤 所有访客：任何人（包括未登录的匿名用户）都可以使用前端浏览和搜索功能
• 👤 文章作者及以上：只有具有 edit_posts 能力的已登录用户才能使用
• 👤 仅管理员：只有具有 manage_options 能力的管理员才能使用

配置完成后，点击"保存设置"按钮。如果连接成功，你就可以开始使用插件的各项功能了。

4.4 验证连接

配置完成后，进入 Trilium Notes → 浏览笔记 页面来验证连接是否正常。在搜索框中输入任意关键词，点击搜索。如果能看到来自你 Trilium 笔记的搜索结果，说明连接配置正确。

如果搜索无结果或出现错误，请检查以下几点：

• 🔍 API 地址是否正确，是否以 /etapi 结尾
• 🔍 ETAPI Token 是否正确，是否过期
• 🔍 WordPress 服务器是否能通过网络访问 Trilium 服务器（防火墙、端口是否开放）
• 🔍 如果使用 HTTPS，SSL 证书是否有效（或是否已关闭 SSL 验证选项）

五、管理后台功能详解

5.1 仪表盘页面

进入 Trilium Notes → Trilium WP 即可访问插件的仪表盘页面。这是一个快速导航和参考页面，提供以下内容：

• 🏠 快速跳转到"设置"和"浏览笔记"页面的链接
• 🏠 所有六个短代码的完整参考文档，包括参数说明和使用示例
• 🏠 常见问题解答和使用提示

这个页面本质上是一个"备忘录"，在你记不清某个短代码的参数名称时，可以快速查阅。

5.2 浏览笔记页面

Trilium Notes → 浏览笔记 页面是管理后台中最实用的功能之一。它提供了一个直接在 WordPress 后台搜索和预览 Trilium 笔记的界面。

搜索功能

在搜索框中，你可以使用 Trilium 的查询语法来精确查找笔记。这里列举一些常用的查询语法：

💡 搜索框旁边有一个"帮助"按钮（带有问号图标），点击后会弹出更完整的查询语法参考。

搜索结果操作

搜索结果以列表形式展示，每条结果显示笔记标题和笔记 ID。对于每条结果，你可以执行以下操作：

• 👁️ 查看内容：点击笔记标题展开/折叠笔记内容预览
• 📋 复制短代码：点击"复制短代码"按钮，自动将该笔记的短代码（如 [trilium_note id="abc123"]）复制到剪贴板，方便你直接粘贴到文章编辑器中

5.3 管理缓存

缓存管理虽然没有单独的界面页面，但理解缓存行为对于日常使用非常重要。

当你在 Trilium 中更新了笔记内容，WordPress 站点上不会立即反映变化——因为旧内容被缓存了。缓存会在到期后自动刷新（到期时间取决于你在设置中配置的"缓存时间"值）。

如果你需要立即看到更新，有以下几种方式：

• 🔄 等待缓存自然过期：最简单的方式，适合非紧急情况
• 🔄 清除全部缓存：在插件设置页面可以触发清除所有 Trilium 相关的缓存数据
• 🔄 调整缓存时间：将缓存时间设置为较短的值（如 300 秒 = 5 分钟），可以更频繁地获取最新内容，但会增加 API 调用次数

📌 实践建议：在日常运营中，建议将缓存时间设置为 1800 秒（30 分钟）到 3600 秒（1 小时）之间。在集中更新内容的阶段，可以临时缩短为 300 秒。

六、短代码完全指南

短代码是 Trilium WP 的核心交互方式。你通过在 WordPress 的文章、页面或小工具中插入特定格式的短代码标签，来嵌入 Trilium 笔记的各种内容和功能。本章将逐一详解六个短代码的使用方法。

6.1 嵌入单篇笔记：[trilium_note]

这是最基础也是最常用的短代码，用于在页面中嵌入一篇特定的 Trilium 笔记。

基本语法

[trilium_note id="笔记ID"]

参数说明

使用示例

嵌入一篇笔记并显示目录：

[trilium_note id="abc123XYZ"]

嵌入笔记但不显示目录：

[trilium_note id="abc123XYZ" toc="false"]

嵌入笔记并显示所有附加信息：

[trilium_note id="abc123XYZ" toc="true" show_sync_status="true" show_meta="true"]

如何获取笔记 ID

获取 Trilium 笔记 ID 有两种方式：

1. 🔗 从 Trilium 应用中获取：在 Trilium Notes 中打开目标笔记，在笔记属性面板或 URL 中可以找到笔记 ID（通常是一串字母和数字的组合）
2. 🔗 从 WordPress 后台浏览器获取：在 Trilium Notes → 浏览笔记 页面搜索到目标笔记后，直接点击"复制短代码"按钮

目录功能详解

当 toc="true"（默认启用）时，插件会自动扫描笔记内容中的 H2 和 H3 标题标签，生成一个可点击的目录导航。点击目录项会平滑滚动到对应的标题位置。

💡 如果你的 WordPress 主题使用了固定定位的顶部导航栏，点击目录后页面可能会滚动到错误的位置（标题被导航栏遮挡）。此时可以在插件设置中调整"目录滚动偏移"参数，设置一个正整数值（如 80），让滚动目标位置向下偏移相应的像素数。

6.2 搜索笔记：[trilium_search]

这个短代码用于在页面中嵌入一组搜索结果，展示满足特定查询条件的笔记列表。

基本语法

[trilium_search query="查询表达式"]

参数说明

使用示例

搜索所有带有 #published 标签的笔记，最多显示 10 条：

[trilium_search query="#published" limit="10"]

搜索标题中包含"教程"的笔记：

[trilium_search query="note.title =* '教程'" limit="8"]

搜索所有代码类型的笔记：

[trilium_search query="note.type = code" limit="20"]

显示效果

搜索结果以卡片列表形式展示，每张卡片显示笔记标题和可展开的内容预览。用户点击标题可以展开查看完整内容，再次点击折叠。

💡 使用建议：此短代码适合用于创建"专题聚合页"，例如将所有标记了特定标签的笔记集中展示在一个 WordPress 页面上。通过合理使用 Trilium 的标签系统，你可以实现非常灵活的内容聚合。

6.3 前端浏览器：[trilium_browser]

这个短代码嵌入了一个完整的前端笔记搜索和浏览界面，让访客可以直接在你的网站上搜索和阅读 Trilium 笔记。

基本语法

[trilium_browser]

此短代码没有参数，直接插入即可。

功能特性

嵌入后，页面上会出现一个包含以下元素的交互界面：

• 🔎 搜索输入框：访客可以在此输入关键词或 Trilium 查询语法来搜索笔记
• 🔎 搜索结果列表：搜索结果以分批加载的方式展示，每批 20 条，滚动到底部或点击"加载更多"按钮可以加载下一批
• 🔎 内容预览：点击搜索结果中的笔记标题可以展开查看完整内容
• 🔎 路径信息：每条搜索结果显示笔记在 Trilium 中的完整层级路径，帮助用户了解笔记的上下文位置

使用场景

• 📌 将你的 Trilium 笔记库作为一个可搜索的知识库对外开放
• 📌 在团队内部站点提供笔记搜索入口
• 📌 为读者提供一种自主探索你笔记内容的方式

权限控制

前端浏览器的访问受到插件设置中"前端访问权限"的控制。如果当前用户的权限不满足要求，浏览器界面不会渲染，页面上将显示一条权限不足的提示信息。

6.4 知识库：[trilium_kb]

这是 Trilium WP 功能最丰富的短代码，它将一个 Trilium 笔记的子树构建为一个完整的、带有侧边栏导航的知识库系统。

基本语法

[trilium_kb root_id="根笔记ID"]

参数说明

使用示例

创建一个标题为"技术文档"的知识库：

[trilium_kb root_id="techDocRoot" title="技术文档" max_items="200"]

知识库界面构成

嵌入的知识库界面由以下几个部分组成：

🗂️ 左侧边栏——导航树

• 以树形结构展示根笔记下的所有层级
• 包含子笔记的节点前显示展开/折叠箭头
• 点击节点即可在右侧内容区加载对应笔记
• 侧边栏顶部有一个搜索框，可以在知识库范围内搜索笔记
• 侧边栏可以通过按钮折叠/展开，折叠状态会在浏览器中记忆

🗂️ 右侧内容区——笔记内容

• 显示当前选中笔记的完整内容
• 顶部有面包屑导航，显示从根节点到当前笔记的完整路径，每个路径节点都可以点击跳转
• 支持自动生成的目录导航（如果笔记内容包含 H2/H3 标题）

🗂️ 默认首页——最近更新

• 当没有选中任何具体笔记时，内容区默认显示"最近更新"列表
• 列出知识库中最近被修改的笔记，附带相对时间标签（如"2 小时前"、"3 天前"）
• 最近更新的时间范围和条数受插件全局设置控制

组织你的知识库

要让知识库呈现最佳效果，建议在 Trilium 中按以下方式组织笔记结构：

根笔记（用作 root_id）
├── 分类一
│   ├── 子主题 A
│   │   ├── 详细文章 1
│   │   └── 详细文章 2
│   └── 子主题 B
├── 分类二
│   ├── 子主题 C
│   └── 子主题 D
└── 分类三
    └── ...

💡 性能提示：max_items 参数控制知识库初始加载的笔记总量。如果你的笔记树非常庞大（超过 500 个节点），建议适当降低此值或将知识库拆分为多个较小的子库，以保证加载速度。

6.5 相关笔记：[trilium_related_notes]

这个短代码用于在文章页面中展示与当前 WordPress 文章标题相关的 Trilium 笔记，实现"跨平台内容关联"。

基本语法

[trilium_related_notes]

此短代码没有参数。它会自动获取当前 WordPress 文章或页面的标题，然后在 Trilium 中搜索标题或内容与之相关的笔记。

显示效果

搜索到的相关笔记以可展开的卡片形式呈现。默认情况下只显示笔记标题，用户点击后可以展开查看完整内容。

使用场景

• 📎 在博客文章底部添加"相关笔记"版块，为读者提供更多参考资料
• 📎 在教程页面关联相关的技术笔记和代码片段
• 📎 将 WordPress 的公开内容与 Trilium 中更深入的笔记连接起来

💡 效果提示：相关笔记的匹配质量取决于 Trilium 的搜索算法和你的笔记组织方式。为了获得更好的匹配效果，建议让 Trilium 中的笔记标题使用清晰、具体的关键词。

6.6 最近更新：[trilium_recent]

这个短代码展示最近被更新过的 Trilium 笔记列表，适合用于"动态"或"最新内容"展示场景。

基本语法

[trilium_recent]

参数说明

使用示例

显示最近 7 天内更新的笔记，3 列布局，最多 12 条：

[trilium_recent days="7" limit="12" columns="3"]

单列布局，不显示路径，最多 5 条：

[trilium_recent columns="1" show_path="false" limit="5"]

显示效果

每个笔记卡片包含以下信息：

• 📰 笔记标题
• 📰 笔记类型图标（文本、代码、图片等不同类型有不同的图标标识）
• 📰 层级路径（如果 show_path="true"）
• 📰 相对更新时间（如"2 小时前"、"昨天"、"3 天前"）
• 📰 可展开的内容预览（点击标题或展开按钮查看完整内容）

💡 使用建议：此短代码非常适合放在网站首页或侧边栏小工具中，让访客看到你最近在研究和写作的内容，营造"活跃更新"的氛围。

七、内容类型与渲染规则

Trilium Notes 支持多种笔记类型，Trilium WP 对每种类型都有特定的渲染策略。理解这些策略有助于你更好地组织和展示内容。

7.1 文本笔记

这是最常见的笔记类型，也是渲染效果最好的类型。Trilium 中的文本笔记以 HTML 格式存储，插件会直接输出这些 HTML 内容，同时处理其中的图片引用路径。

📝 渲染效果：完整保留原始格式，包括标题、段落、列表、表格、加粗/斜体等所有 HTML 格式元素。

📝 注意事项：Trilium 的 HTML 编辑器生成的样式可能与你的 WordPress 主题存在冲突。Trilium WP 提供了专门的 trilium-content.css 样式表来规范笔记内容的显示，但如果遇到样式问题，你可能需要在主题的自定义 CSS 中添加覆盖规则。

7.2 代码笔记

代码笔记会被渲染为带有语法高亮标识的代码块。

💻 渲染效果：代码被包裹在 <pre><code> 标签中，并根据笔记的 MIME 类型（如 application/javascript、text/x-python 等）添加对应的语言类名。

💻 支持的语言映射（部分）：

💻 提示：如果你的 WordPress 主题或其他插件安装了代码语法高亮库（如 Prism.js 或 Highlight.js），Trilium WP 输出的代码块可以自动与这些库配合工作。

7.3 图片笔记

图片笔记会通过 WordPress 的 AJAX 代理加载显示。

🖼️ 渲染效果：图片以 <img> 标签形式嵌入页面，图片数据通过 WordPress 服务器中转传输，不会直接暴露 Trilium 服务器地址。

🖼️ 支持的图片格式：JPEG、PNG、GIF、SVG。

7.4 PDF/文件笔记

文件类型的笔记（包括 PDF）会提供下载和预览入口。

📄 渲染效果：显示一个包含文件名和操作按钮的界面，用户可以选择下载文件或在浏览器中预览（仅 PDF 支持内联预览）。

7.5 其他笔记类型

对于搜索笔记、关系图笔记、书籍笔记等特殊类型，Trilium WP 会显示一条友好的说明信息，告知用户该类型笔记的用途和特点。这些类型的笔记在 Trilium 中有特殊功能，但其内容暂时无法直接在 WordPress 中渲染。

八、高级用法与实战场景

8.1 构建企业级知识库站点

利用 Trilium WP，你可以将一个 WordPress 站点打造为完整的企业或团队知识库平台。以下是推荐的架构方案：

站点结构规划

工作流程建议

在 Trilium 中撰写和组织笔记
         ↓
使用标签（labels）进行分类标记
         ↓
在 WordPress 中通过短代码引用
         ↓
WordPress 通过 API 实时获取内容
         ↓
访客通过 WordPress 站点浏览知识

这种架构的优势在于：你始终在 Trilium 中管理内容（享受 Trilium 强大的笔记组织能力），WordPress 只负责展示（享受 WordPress 丰富的主题和 SEO 能力）。

8.2 短代码组合使用

你可以在同一个页面中组合使用多个短代码，创造丰富的内容布局。例如：

<!-- 页面顶部：嵌入一篇介绍性笔记 -->
[trilium_note id="introNoteId" toc="false"]

<!-- 中间区域：展示最近更新 -->
<h2>最近更新的内容</h2>
[trilium_recent days="14" limit="6" columns="3"]

<!-- 底部区域：搜索特定标签的笔记 -->
<h2>推荐阅读</h2>
[trilium_search query="#recommended" limit="5"]

8.3 性能优化策略

当你的 Trilium 笔记库规模较大时，合理的性能优化策略能显著提升站点体验：

⚡ 缓存时间调优：

• 内容变动频繁的站点：设置 300-600 秒（5-10 分钟）
• 内容相对稳定的站点：设置 3600-7200 秒（1-2 小时）
• 纯展示型站点：设置 43200 秒（12 小时）甚至更长

⚡ 知识库规模控制：

• 单个知识库的 max_items 建议不超过 300
• 如果笔记总量超过 500，考虑按主题拆分为多个知识库
• 深层嵌套（超过 5 层）的笔记树会增加导航复杂度，建议控制在 3-4 层

⚡ 搜索结果限制：

• [trilium_search] 的 limit 参数不宜设置过大
• 前端浏览器 [trilium_browser] 采用分批加载机制，每次 20 条，天然具有良好的性能表现

8.4 主题兼容性处理

Trilium WP 默认针对 BuddyBoss 主题进行了深度适配。如果你使用其他主题，可能需要添加一些自定义 CSS 来修正样式问题。常见的兼容性问题和解决方案包括：

🎨 内容区域宽度不一致：在主题的自定义 CSS 中，为 .trilium-note-content 设置 max-width 和 margin 来控制笔记内容的宽度和居中。

🎨 目录位置偏移：如果你的主题有固定头部，调整插件设置中的"目录滚动偏移"参数。通常设置为头部导航栏的高度值（如 60-80 像素）即可。

🎨 暗色模式适配：Trilium WP 内置了对 prefers-color-scheme: dark 媒体查询的支持，如果你的主题使用自定义的暗色模式 CSS 类名，可能需要额外的样式覆盖。

🎨 代码块样式：不同主题对 <pre> 和 <code> 标签的默认样式不同，如果代码笔记的显示效果不理想，可以针对 .trilium-code-block 类名添加自定义样式。

8.5 安全性最佳实践

在实际部署中，以下安全建议值得遵循：

🔐 最小权限原则：如果你的站点不需要对外公开 Trilium 笔记的搜索和浏览功能，请将"前端访问权限"设置为"仅管理员"。

🔐 使用 HTTPS：确保 WordPress 站点和 Trilium 服务器都启用了 HTTPS，保护 API 通信中的数据安全。

🔐 定期更换 Token：建议定期更换 ETAPI Token，降低 Token 泄露后的风险窗口。

🔐 审慎发布笔记：通过短代码嵌入的笔记对所有页面访客可见，请确保不会意外公开敏感或私密的笔记内容。

🔐 保持更新：及时更新 WordPress、Trilium Notes 和 Trilium WP 插件到最新版本，以获取安全修复和功能改进。

九、故障排除

9.1 常见问题诊断表

9.2 调试步骤

当遇到无法快速定位的问题时，建议按以下步骤进行系统性排查：

1. 🔍 验证 Trilium 服务器状态：直接在浏览器中访问 Trilium Web 界面（如 https://your-trilium.com），确认服务器正常运行
2. 🔍 测试 API 连通性：在浏览器或使用 curl 命令直接访问 ETAPI 端点（如 https://your-trilium.com/etapi/app-info），携带 Token 头部，检查是否能获得正常响应
3. 🔍 检查 WordPress 错误日志：在 wp-config.php 中启用 WP_DEBUG 和 WP_DEBUG_LOG，然后查看 wp-content/debug.log 中是否有相关错误信息
4. 🔍 检查浏览器控制台：打开浏览器开发者工具（F12），查看 Console 面板中是否有 JavaScript 错误，以及 Network 面板中 AJAX 请求的状态码和响应内容
5. 🔍 临时禁用缓存：将缓存时间设置为 0（或一个很小的值如 1），排除缓存导致的问题
6. 🔍 排除插件冲突：临时禁用其他 WordPress 插件，逐一启用以定位是否存在插件冲突

十、课程总结与展望

本节课程从两个维度全面解析了 Trilium WP 插件。

在开发原理部分，我们了解了：

• 📖 WordPress 插件的基本架构和钩子系统的工作原理
• 📖 开发此类插件所需的多层知识储备（PHP、JavaScript、WordPress API、RESTful API 等）
• 📖 Trilium WP 的代码架构和关注点分离的设计原则
• 📖 各核心模块（API 通信、短代码系统、内容处理器、图片代理、知识库导航、缓存管理、安全机制）的实现逻辑

在使用教程部分，我们掌握了：

• 📖 从安装配置到连接验证的完整流程
• 📖 管理后台各功能页面的使用方法
• 📖 六个短代码的详细参数、使用示例和适用场景
• 📖 不同笔记类型的渲染规则和注意事项
• 📖 高级实战场景（企业级知识库构建、短代码组合、性能优化、主题兼容性处理、安全实践）
• 📖 系统性的故障排除方法