从源码到个性化：Trilium Notes 开发者完全指南

【免费下载链接】trilium Build your personal knowledge base with Trilium Notes 项目地址: https://gitcode.com/gh_mirrors/tr/trilium

你是否曾想过定制自己的笔记应用，却被复杂的源码结构吓退？本文将带你从零开始构建Trilium Notes，掌握核心模块开发，轻松实现个性化功能。读完本文，你将获得：

• 3步完成源码环境搭建
• 核心模块架构全景图
• 5分钟实现自定义笔记属性
• 贡献代码的完整流程

项目概述：认识Trilium Notes

Trilium Notes是一款开源个人知识库应用，支持层次化笔记管理、富文本编辑、笔记加密和同步功能。作为采用Electron框架开发的跨平台应用，它既能作为桌面程序运行，也可部署为Web服务。

项目核心特性：

• 树状笔记结构与克隆功能
• 所见即所得编辑器与Markdown支持
• 笔记属性系统与脚本自动化
• 端到端加密与自托管同步

项目源码结构采用模块化设计，主要分为：

src/
├── becca/        # 数据模型层
├── services/     # 业务逻辑服务
├── routes/       # API路由
├── etapi/        # 外部API接口
└── public/       # 前端资源

开发环境搭建：3步启动

1. 准备工作

确保系统安装：

• Node.js (v14.0+)
• npm (v6.0+)
• Git

克隆代码库：

git clone https://gitcode.com/gh_mirrors/tr/trilium.git
cd trilium

2. 安装依赖

npm install

注意：Windows用户可能需要安装windows-build-tools：npm install --global --production windows-build-tools

3. 启动开发服务器

# Web服务器模式
npm run start-server

# 桌面应用模式
npm run start-electron

应用启动流程解析：

核心启动代码位于src/www.js和src/app.js，其中www.js处理进程管理，app.js负责Express应用配置。

核心架构解析

数据模型层：Becca

Becca模块是Trilium的数据核心，负责笔记、属性等实体的管理。主要实体包括：

• BNote：笔记实体
• BAttribute：属性实体
• BBranch：笔记分支关系
• BRevision：笔记版本

代码位置：src/becca/entities

业务服务层

Services目录包含应用核心功能实现：

模块	功能	代码位置
notes	笔记管理	src/services/notes.js
attributes	属性系统	src/services/attributes.js
sync	同步服务	src/services/sync.js
backup	备份功能	src/services/backup.js

API接口层

• 内部API：src/routes/api
• 外部API：src/etapi，遵循OpenAPI规范(src/etapi/etapi.openapi.yaml)

自定义功能开发：实战示例

添加自定义属性

1. 创建属性定义文件：

// src/services/builtin_attributes.js
.addAttributeType({
    type: 'label',
    name: 'custom-tag',
    label: '自定义标签',
    isBuiltIn: true,
    isBoolean: false,
    isReadOnly: false
});

2. 在笔记服务中添加处理逻辑：

// src/services/notes.js
async function applyCustomTag(noteId, tagValue) {
    const note = await becca.getNote(noteId);
    await note.setAttribute('label', 'custom-tag', tagValue);
    return note;
}

3. 添加API端点：

// src/routes/api/notes.js
router.post('/:noteId/custom-tag', async (req, res) => {
    const note = await notesService.applyCustomTag(
        req.params.noteId,
        req.body.tagValue
    );
    res.json(note.toJSON());
});

扩展编辑器功能

通过修改CKEditor配置添加自定义按钮：

// src/public/app/widgets/note_text.js
editor.ui.componentFactory.add('customButton', () => {
    const button = editor.ui.view.addButton('CustomButton', {
        label: '插入自定义内容',
        action: () => {
            editor.model.change(writer => {
                editor.model.insertContent(
                    writer.createText('自定义内容')
                );
            });
        }
    });
    return button;
});

调试与测试

调试配置

VS Code调试配置示例：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "启动服务器",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "start-server"]
        },
        {
            "type": "node",
            "request": "launch",
            "name": "启动Electron",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "start-electron"]
        }
    ]
}

运行测试

# 单元测试
npm run test-jasmine

# API测试
npm run test-es6

测试用例位于spec/目录，包含API测试和服务层测试。

贡献代码

贡献流程

1. Fork代码库
2. 创建特性分支：git checkout -b feature/my-feature
3. 提交更改：git commit -m "Add custom feature"
4. 推送分支：git push origin feature/my-feature
5. 创建Pull Request

代码规范

• 使用ESLint检查代码：npm run lint
• 遵循项目注释规范，使用JSDoc格式
• 所有新功能需添加测试用例

高级资源

官方文档

• 后端API文档：docs/backend_api/index.html
• 前端API文档：docs/frontend_api/index.html

核心模块详解

• 同步机制：src/services/sync.js
• 加密服务：src/services/encryption
• 导入导出：src/services/import和src/services/export

总结与展望

通过本文，你已掌握Trilium Notes的源码构建、架构解析和自定义开发基础。项目正处于活跃开发中，未来将支持更多AI集成和协作功能。

立即行动：

1. Star项目仓库
2. 尝试实现第一个自定义属性
3. 加入社区讨论分享你的想法

下一篇：《Trilium Notes插件开发指南：从构思到发布》

---

开发资源速查表

功能	代码位置
启动入口	src/www.js
应用配置	src/app.js
数据模型	src/becca
API路由	src/routes/api
前端组件	src/public/app/components

常用命令

# 构建API文档
npm run build-docs

# 打包应用
npm run pack

# 运行代码检查
npm run lint

【免费下载链接】trilium Build your personal knowledge base with Trilium Notes 项目地址: https://gitcode.com/gh_mirrors/tr/trilium