trilium ICO 设置手册

Trilium ICO 设置手册

概述

本文档记录 Trilium 笔记分享功能的图标文件配置方法，包括 Favicon（浏览器标签图标）和 Open Graph Logo（Google 搜索结果/社交分享图标）的设置。

Trilium 分享图标机制

Trilium 通过三种关系标签控制分享页面的图标：

属性	类型	作用	HTML 输出
`shareFavicon`	关系	浏览器标签页图标、书签图标	`<link rel="icon">`
`shareLogo`	关系	Google 搜索结果图标、社交媒体预览图	`<meta property="og:image">`
`shareCss`	关系	页面自定义样式	`<link rel="stylesheet">`

属性位置

设置在分享树的根节点上（即设置了 shareAlias 的笔记，或任意祖先笔记）
必须标记为 isInheritable: true（可继承），子笔记会自动继承
当前设置位置：知识库 (ugfQKTnlcOzn)，通过继承覆盖到所有子笔记

服务器上的 ICO/图标文件

当前在 已安装扩展主题 (4mKyL1O34L1t) 下存放了以下图标文件：

笔记 ID	文件名	格式	尺寸	用途
`UIvXoO2yeaap`	thinkpad_48_48.ico	ICO ✅	48×48	→ shareFavicon（Tab 图标，已启用）
`NnitAKmB921f`	thinkpad_512_512.jpg	JPEG ✅	512×512 ✅	→ shareLogo（Google 搜索结果，已切换）
`zDOa2Hxg4lBI`	thinkpad_53_46.jpg	JPEG ✅	53×46 ❌ 太小	原 shareLogo，已停用

配置步骤

Favicon 设置（浏览器 Tab 图标 + 书签）

准备一个 .ico 格式图标（支持多尺寸，推荐 16×16 + 32×32 + 48×48 组合）
在 Trilium 中上传为图片笔记（拖入即可）
在分享根笔记上添加关系标签：
- 类型：relation（关系）
- 名称：shareFavicon
- 值：指向上传的图标笔记
- 可继承：true ✓

OG Logo 设置（Google 搜索结果 + 社交分享）

准备一张 至少 200×200 的图片（推荐 512×512 或 1200×630）
在 Trilium 中上传为图片笔记
核对 MIME 类型 — 在 Trilium 中查看笔记属性，确保 MIME 与实际格式一致：
- JPEG 文件 → image/jpeg
- PNG 文件 → image/png
- ICO 文件 → image/ico
在分享根笔记上添加/修改关系标签：
- 类型：relation（关系）
- 名称：shareLogo
- 值：指向上传的图片笔记
- 可继承：true ✓
修改后需通知 Google Search Console 重新抓取页面，OG 图片才会更新

Nginx 修复书签图标

浏览器在保存书签时，除了读取页面内的 <link rel="icon">，还会额外请求网站根路径的 /favicon.ico。Trilium 不在根路径自动提供该文件，因此书签收藏夹图标空白。

通过在 Nginx 中写死 /favicon.ico 路由即可解决。

Trilium 图片 API 路径说明

通过测试确认，Trilium 文件下载的正确 API 路径格式为：

/share/api/images/{noteId}/{filename}

例如：https://trilium.atibm.com/share/api/images/UIvXoO2yeaap/thinkpad_48_48.ico

该路径返回 Content-Type: image/ico ✅，可直接用于 Nginx proxy_pass。

❌ /api/notes/{noteId}/download/{filename} 需要认证，不可直接用于 proxy_pass。

Nginx 配置

在 Trilium 的 Nginx server block 内添加：

location = /favicon.ico {
    # 方式一：直接指向本地静态文件（推荐）
    alias /var/www/favicon.ico;

    # 方式二：代理到 Trilium 已有图标的下载链接（无需认证）
    proxy_pass https://trilium.atibm.com/share/api/images/UIvXoO2yeaap/thinkpad_48_48.ico;

    expires 30d;
    access_log off;
    log_not_found off;
    add_header Cache-Control "public, immutable";
}

两种方式对比

方式	操作	优点	缺点
① 静态文件（推荐）	把 .ico 文件复制到 Nginx 目录	不依赖 Trilium 进程，性能最好	每次换图标需手动同步
② 代理到 Trilium	proxy_pass 到 `/share/api/images/...`	换图标只需在 Trilium 里换，Nginx 不用改	依赖 Trilium 进程，多一次内部请求

操作方法

# 方式①：从 Trilium 导出 ICO 到 Nginx 目录
curl -o /var/www/favicon.ico "https://trilium.atibm.com/share/api/images/UIvXoO2yeaap/thinkpad_48_48.ico"

# 测试并重载 Nginx
nginx -t && nginx -s reload

如何不改变 Note ID 替换图标文件

核心原则：Trilium 的 noteId 是永久不变的，只有新建笔记才会生成新 ID。因此替换图标时只需原地更新已有笔记内容，避免删除重建。

这样，shareFavicon / shareLogo 的关系标签和 Nginx proxy_pass URL 都无需改动。

方法一：Trilium 界面操作（推荐）

在 Trilium 中找到目标 ICO 图片笔记
右键笔记 → Edit（编辑）
在 CKEditor 编辑器中，删除旧图片，拖入新 ICO 文件替换
保存 → noteId 不变，文件内容已更新

方法二：方式①（静态文件）的替换

如果用 Nginx 方式①（静态文件），替换更简单：直接复制新 ICO 覆盖 /var/www/favicon.ico，Nginx 无需重载：

cp /path/to/new-icon.ico /var/www/favicon.ico

常见问题与排查

浏览器 Tab 有图标，但 Google 搜索结果没有

原因：shareLogo 指向的图片太小（Google 要求 ≥200×200）或 MIME 类型错误。

解决：上传 ≥200×200 的图片作为 shareLogo，确保 MIME 正确。

Tab 有图标，但书签收藏夹没有

原因：浏览器保存书签时会额外请求 /favicon.ico 根路径，Trilium 不自动提供。

解决：在 Nginx 中配置 location = /favicon.ico 指向静态 ICO 文件（参见上方 Nginx 章节）。

图标完全不显示

原因：shareFavicon / shareLogo 的关系标签没有设置 isInheritable: true。

解决：确保关系标签标记为可继承。

MIME 类型不正确

原因：Trilium 可能自动识别文件类型有误。常见错误 MIME：

image/jpg → ❌ 非标准，应改为 image/jpeg
image/x-icon → ❌ 旧标准，建议 image/ico（Trilium 可识别）

解决：通过 Trilium 笔记属性直接修改 MIME 字段。

操作记录

日期	操作
2026-05-15	修复 `thinkpad_53_46` MIME: `image/jpg` → `image/jpeg`
2026-05-15	修复 `thinkpad_512_512` MIME: `image/jpg` → `image/jpeg`
2026-05-15	切换 `shareLogo`: 53×46 → 512×512
2026-05-15	确认正确 API 路径: `/share/api/images/{noteId}/{filename}`（无需认证）