3个超实用技巧：Trilium Notes脚本编程从入门到精通

2026-04-07 11:37:19作者：何举烈Damon

发现痛点：知识管理中的效率瓶颈

你是否每天花费大量时间在笔记整理上？手动为笔记添加标签、重复创建相似结构的笔记、在成百上千条笔记中寻找关联内容——这些机械操作正在消耗你宝贵的思考时间。Trilium Notes作为一款强大的个人知识库工具，其内置的脚本编程功能正是解决这些问题的钥匙。本文将通过三个递进式场景，带你掌握从基础应用到系统集成的全流程脚本开发，让知识管理真正自动化、智能化。

解锁核心能力：Trilium脚本编程基础

认识前后端双引擎架构

Trilium提供两套独立又互补的脚本运行环境，就像为知识管理配备了"左右脑"：

后端脚本：运行在服务器环境，拥有数据库操作权限，适合处理数据密集型任务。想象成图书馆的管理员，能直接接触所有书籍和档案。
前端脚本：运行在浏览器环境，专注于用户界面交互，适合创建交互式工具。如同图书馆的导览系统，帮助用户更直观地使用馆藏资源。

开发环境快速搭建

创建一个基础脚本只需三步：

新建笔记，设置类型为"code"
设置MIME类型为"application/javascript"
添加#run=backend或#run=frontend属性指定运行环境

点击笔记工具栏中的▶️按钮即可执行脚本，结果会显示在下方输出面板中。

核心API初探

后端API提供了操作笔记的基础能力，以下是最常用的几个方法：

// 创建文本笔记
const {note, branch} = api.createTextNote(parentNoteId, title, content);

// 搜索笔记（支持Trilium查询语法）
const results = api.searchForNotes("#tag:important AND #type:document");

// 事务处理（确保多个操作的原子性）
api.transactional(() => {
  // 批量操作代码
});

技巧提示：所有API调用都应放在try-catch块中，以便捕获和处理可能的错误。

场景实践一：基础应用——自动化标签管理

痛点引入：混乱的标签系统

随着笔记数量增长，手动管理标签变得越来越困难。重要笔记被遗忘在标签海洋中，相关内容难以关联，知识体系变得支离破碎。

解决方案：智能标签助手

这个后端脚本将自动分析新笔记内容，提取关键词并生成相关标签，保持标签系统的一致性和实用性。

// == 智能标签助手 ==
// 1. 获取最近24小时创建的未处理笔记
const newNotes = api.searchForNotes(`#created:>="${api.dayjs().subtract(1, 'day').format('YYYY-MM-DD')}" -#auto-tagged`);

if (newNotes.length === 0) {
  api.log("没有需要处理的新笔记");
  return;
}

// 2. 处理每个笔记
api.transactional(() => {
  newNotes.forEach(note => {
    try {
      // 提取内容和标题
      const content = note.getContent();
      const title = note.title;
      
      // 3. 提取关键词（简化实现）
      const keywords = extractKeywords(title, content);
      
      // 4. 添加标签
      keywords.forEach(keyword => {
        // 只添加长度大于3的关键词作为标签
        if (keyword.length > 3) {
          note.addLabel("tag", keyword);
          api.log(`为笔记 "${title}" 添加标签: ${keyword}`);
        }
      });
      
      // 5. 标记为已处理
      note.addLabel("auto-tagged", "true");
      note.save();
    } catch (e) {
      api.log(`处理笔记 "${note.title}" 时出错: ${e.message}`);
      // 出错时继续处理下一个笔记
    }
  });
});

// 辅助函数：提取关键词
function extractKeywords(title, content) {
  // 合并标题和内容并转为小写
  const text = (title + " " + content).toLowerCase();
  
  // 简单分词和过滤
  const words = text.match(/\b[a-zA-Z0-9]{4,}\b/g) || [];
  
  // 过滤常见无意义词
  const stopWords = ["the", "and", "for", "with", "have", "this", "that"];
  return words.filter(word => !stopWords.includes(word))
              .slice(0, 5); // 最多取5个关键词
}

注意事项：关键词提取算法可以根据个人需求优化，实际应用中可考虑使用TF-IDF或TextRank等更复杂的算法提升准确性。

实践检验

创建一篇包含多个专业术语的新笔记
运行脚本后检查标签是否自动添加
验证相同主题的笔记是否获得一致标签
调整关键词提取算法，观察标签质量变化

场景实践二：效率提升——研究文献自动整理

痛点引入：科研文献管理困境

研究人员经常需要处理大量PDF论文，手动提取摘要、作者、期刊等信息并分类保存，这个过程繁琐且容易出错，严重影响研究效率。

解决方案：文献管理自动化工作流

以下脚本将监控指定目录，自动导入新PDF文件，提取元数据，并按期刊和年份组织文献笔记，让你专注于内容理解而非机械操作。

// == 科研文献自动处理系统 ==
const WATCH_DIR = "/home/user/research/papers"; // 监控目录
const LIBRARY_ROOT = "research-library"; // 文献库根笔记ID

// 1. 检查是否有新PDF文件
const newFiles = api.listFiles(WATCH_DIR, {
  pattern: "*.pdf",
  modifiedAfter: api.getOption("last_paper_import_time") || "2020-01-01"
});

if (newFiles.length === 0) {
  api.log("没有发现新的PDF文件");
  return;
}

// 2. 处理每个PDF文件
api.transactional(async () => {
  for (const file of newFiles) {
    try {
      // 3. 提取PDF元数据
      const metadata = await api.extractPdfMetadata(file.path);
      
      // 4. 创建文献笔记
      const title = metadata.title || api.path.basename(file.path, ".pdf");
      const authors = metadata.authors ? metadata.authors.join(", ") : "未知作者";
      const year = metadata.year || "未知年份";
      const journal = metadata.journal || "未分类";
      
      // 5. 创建期刊和年份分类笔记（如果不存在）
      const journalNote = await getOrCreateNote(LIBRARY_ROOT, journal, "journal");
      const yearNote = await getOrCreateNote(journalNote.noteId, year, "year");
      
      // 6. 创建文献笔记并附加PDF
      const {note: paperNote} = api.createTextNote(
        yearNote.noteId,
        title,
        generatePaperNoteContent(metadata, authors)
      );
      
      // 7. 上传并附加PDF文件
      await api.uploadAttachment(paperNote.noteId, file.path);
      
      // 8. 添加标签和属性
      paperNote.addLabel("type", "paper");
      paperNote.addLabel("authors", authors);
      paperNote.addLabel("year", year);
      paperNote.setLabel("status", "unread");
      paperNote.save();
      
      api.log(`成功导入文献: ${title}`);
    } catch (e) {
      api.log(`处理文件 ${file.path} 时出错: ${e.message}`);
    }
  }
  
  // 9. 更新最后导入时间
  api.setOption("last_paper_import_time", new Date().toISOString());
});

// 辅助函数：获取或创建分类笔记
async function getOrCreateNote(parentNoteId, title, type) {
  const existing = api.searchForNotes(`parent:${parentNoteId} title:"${title}"`)[0];
  if (existing) return existing;
  
  const {note} = api.createTextNote(parentNoteId, title, "");
  note.addLabel("type", type);
  note.save();
  return note;
}

// 辅助函数：生成文献笔记内容
function generatePaperNoteContent(metadata, authors) {
  return `# ${metadata.title || "未知标题"}\n\n` +
         `**作者**: ${authors}\n` +
         `**年份**: ${metadata.year || "未知年份"}\n` +
         `**期刊**: ${metadata.journal || "未知期刊"}\n` +
         `**DOI**: ${metadata.doi || "无"}\n\n` +
         `## 摘要\n\n${metadata.abstract || "无摘要"}\n\n` +
         `## 研究笔记\n\n*在此添加你的阅读笔记...*`;
}

技巧提示：可通过添加#trigger=daily属性使脚本每天自动运行，实现完全自动化的文献管理流程。

实践检验

在监控目录中放入几篇不同期刊的PDF论文
运行脚本后检查文献库结构是否按期刊/年份组织
验证元数据提取准确性，特别是标题、作者和摘要
测试标记为"unread"的文献是否能被单独搜索

场景实践三：系统集成——跨平台知识同步

痛点引入：多设备知识孤岛

在电脑、手机、平板等多设备间同步笔记时，全量同步不仅耗时，还可能在低端设备上造成性能问题。选择性同步关键内容成为提升效率的关键需求。

解决方案：智能同步控制中心

这个高级脚本实现了基于内容重要性和设备特性的选择性同步策略，确保你在任何设备上都能获取最重要的知识，同时优化存储和同步性能。

// == 智能同步控制中心 ==
// 配置区域
const SYNC_CRITERIA = {
  highPriorityTags: ["project:current", "important", "to-read"],
  lowPriorityTags: ["archive", "reference"],
  maxSizeMB: 10, // 单笔记最大同步大小
  mobileExcludeTags: ["large-attachment", "raw-data"]
};

// 1. 拦截同步事件
api.onSyncStart(async (deviceInfo) => {
  try {
    api.log(`开始同步到 ${deviceInfo.type} 设备`);
    
    // 2. 根据设备类型确定同步策略
    const isMobileDevice = deviceInfo.type === "mobile";
    const syncRoot = api.getNoteById("sync-root");
    
    // 3. 构建同步内容查询
    let queryParts = [];
    
    // 添加高优先级内容
    queryParts.push(SYNC_CRITERIA.highPriorityTags.map(tag => `#${tag}`).join(" OR "));
    
    // 排除大文件
    queryParts.push(`-#size:>${SYNC_CRITERIA.maxSizeMB}MB`);
    
    // 移动设备额外排除
    if (isMobileDevice) {
      queryParts.push(SYNC_CRITERIA.mobileExcludeTags.map(tag => `-#${tag}`).join(" AND "));
    }
    
    const syncQuery = queryParts.join(" AND ");
    api.log(`同步查询: ${syncQuery}`);
    
    // 4. 获取符合条件的笔记
    const notesToSync = api.searchForNotes(syncQuery);
    api.log(`找到 ${notesToSync.length} 个符合条件的笔记`);
    
    // 5. 生成同步包
    const syncPackagePath = await api.createSyncPackage({
      notes: notesToSync,
      includeAttachments: !isMobileDevice, // 移动设备可选择不包含附件
      compressionLevel: isMobileDevice ? "high" : "normal"
    });
    
    // 6. 执行同步
    const syncResult = await api.performSync({
      targetDeviceId: deviceInfo.id,
      packagePath: syncPackagePath,
      priority: isMobileDevice ? "high" : "normal"
    });
    
    if (syncResult.success) {
      api.log(`同步成功，传输了 ${syncResult.sizeMB.toFixed(2)} MB`);
      
      // 7. 记录同步状态
      api.setOption(`last_sync_${deviceInfo.id}`, {
        date: new Date().toISOString(),
        noteCount: notesToSync.length,
        sizeMB: syncResult.sizeMB
      });
    } else {
      api.log(`同步失败: ${syncResult.error}`);
      throw new Error(`同步失败: ${syncResult.error}`);
    }
  } catch (e) {
    api.log(`同步过程出错: ${e.message}`, "error");
    // 发送通知
    api.sendNotification({
      title: "同步失败",
      message: `无法完成同步: ${e.message}`,
      priority: "high"
    });
  }
});

// 8. 提供手动触发同步的函数
api.registerGlobalFunction("triggerSync", async (deviceId) => {
  const deviceInfo = api.getDeviceInfo(deviceId);
  if (!deviceInfo) throw new Error("设备不存在");
  
  return api.onSyncStart(deviceInfo);
});

注意事项：同步策略应根据个人使用习惯定期调整，建议通过单独的配置笔记管理同步规则，避免硬编码。

实践检验

在不同设备上配置同步客户端
添加不同标签组合的测试笔记，包括大附件笔记
观察同步结果是否符合预期的筛选规则
使用triggerSync函数测试手动同步功能
检查同步日志和错误处理机制是否正常工作

进阶拓展：脚本开发高级技巧

错误处理与调试策略

健壮的脚本必须包含完善的错误处理机制：

// 高级错误处理模式
async function safeOperation(operation, errorMessage) {
  try {
    return await operation();
  } catch (e) {
    // 详细日志记录
    api.log(`[ERROR] ${errorMessage}: ${e.message}\n${e.stack}`);
    
    // 错误恢复策略
    if (e.type === "database") {
      api.log("尝试数据库连接恢复...");
      await api.reconnectDatabase();
      // 重试一次
      return await operation();
    }
    
    // 无法恢复的错误
    throw new Error(`${errorMessage}: ${e.message}`);
  }
}

// 使用示例
const result = await safeOperation(
  () => api.createTextNote(parentId, title, content),
  `创建笔记 "${title}" 失败`
);

性能优化实践

处理大量笔记时，性能优化至关重要：

批量操作：使用事务减少数据库交互

// 高效的批量创建
api.transactional(() => {
  largeDataset.forEach(item => {
    api.createTextNote(parentId, item.title, item.content);
  });
});

结果缓存：避免重复计算

// 智能缓存实现
function cachedOperation(key, operation, ttl = 3600) {
  const now = Date.now();
  // 检查缓存是否存在且未过期
  if (api.cache[key] && (now - api.cache[key].timestamp) < ttl * 1000) {
    return api.cache[key].data;
  }
  
  // 执行操作并缓存结果
  const result = operation();
  api.cache[key] = {
    data: result,
    timestamp: now
  };
  
  return result;
}

延迟加载：按需处理数据

// 分页处理大量结果
async function processLargeDataset(query, batchSize = 50) {
  let offset = 0;
  let hasMore = true;
  
  while (hasMore) {
    const batch = api.searchForNotes(query, { offset, limit: batchSize });
    if (batch.length === 0) break;
    
    // 处理当前批次
    for (const item of batch) {
      await processItem(item);
    }
    
    offset += batchSize;
    hasMore = batch.length === batchSize;
  }
}