企业官网建设流程全解析

Joplin 自定义 CSS 完整指南：用 userstyle.css 与 userchrome.css 深度定制笔记渲染与桌面端界面

【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin

Joplin 桌面端为高级用户提供了两套基于 CSS 的定制入口：userstyle.css负责定制笔记渲染（Markdown 预览）的样式，userchrome.css负责定制整个应用的界面外观。本文以官方文档 Custom CSS 为核心，结合仓库源码（如 Setting.ts、app.ts）详细讲解这两类文件的位置、加载机制、生效条件、打印注意事项与维护风险，并给出可落地的样式示例，帮助你把 Joplin 调校成符合个人阅读与写作习惯的形态。

一、两个文件，两种作用域：userstyle.css 与 userchrome.css

Joplin 桌面端的 CSS 定制分为两个独立文件，二者作用域完全不同，官方在源码中将其集中定义在 Setting.ts 的customCssFilenames常量中：

public static customCssFilenames = { JOPLIN_APP: 'userchrome.css', RENDERED_MARKDOWN: 'userstyle.css', };

两者的定位差异可以从官方在设置项中写入的默认注释看出（见 builtInMetadata.ts）：userchrome.css的默认文件头注释明确写着"用于样式化整个 Joplin 应用（渲染后的 Markdown 除外，那部分在 userstyle.css 中定义）"。

二、文件存放位置与如何找到你的配置文件路径

这两个文件都存放在 Joplin 的**配置目录（profile directory）**下，文件名固定为userstyle.css与userchrome.css。官方文档给出的典型路径是：

• userstyle.css：~/.config/joplin-desktop/userstyle.css
• userchrome.css：~/.config/joplin-desktop/userchrome.css

但该路径会因操作系统、安装方式与自定义配置目录而不同，文档明确提醒"你的设备上路径可能不同"。最可靠的确认方式有两条：

1. 在配置界面查看：打开 Joplin 的"配置"（Configuration）界面，进入General（常规）页，页面顶部即显示当前配置目录的准确路径。
2. 在"外观"设置中直接打开/创建文件：配置界面的Appearance（外观）区块提供两个按钮（见 builtInMetadata.ts）：
   • Custom stylesheet for rendered Markdown（渲染 Markdown 的自定义样式表）：对应userstyle.css；
   • Custom stylesheet for Joplin-wide app styles（Joplin 全局应用样式）：对应userchrome.css。

点击按钮会调用shim.openOrCreateFile——如果文件不存在则先创建并写入默认注释，然后用系统默认编辑器打开，无需手工记忆路径。这两个设置项均标记为advanced: true，位于外观区块的高级区域。

从源码看，文件的实际解析路径由Setting.customCssFilePath()计算得出（Setting.ts）：

public static customCssFilePath(filename: string): string { return `${this.value('rootProfileDir')}/${filename}`; }

即路径恒等于rootProfileDir（配置根目录）与固定文件名的拼接，这也是为什么文件必须放在配置根目录、且名称必须精确为上述两个名字。

三、加载机制：应用启动时如何读取这两个文件

理解"为什么改了 CSS 有时不生效"，需要先了解加载时机。在 app.ts 中，setupCustomCss()负责启动阶段的两个加载动作：

private async setupCustomCss() { const chromeCssPath = Setting.customCssFilePath(Setting.customCssFilenames.JOPLIN_APP); if (await shim.fsDriver().exists(chromeCssPath)) { this.store().dispatch({ // Main window custom CSS type: 'CUSTOM_CHROME_CSS_ADD', filePath: chromeCssPath, }); } this.store().dispatch({ // Markdown preview pane type: 'CUSTOM_VIEWER_CSS_APPEND', css: await loadCustomCss(Setting.customCssFilePath(Setting.customCssFilenames.RENDERED_MARKDOWN)), }); }

由此可以总结出几条关键结论：

• 两者都在应用启动阶段被加载，因此新增或修改样式后，必须完全退出并重新启动 Joplin才能生效。官方文档特别强调：请确保 Joplin 是真正退出，而不是最小化到系统托盘（tray）——最小化到托盘时进程仍在运行，重启后看到的仍可能是旧样式。
• 加载策略不同：userchrome.css只有在文件已存在时才被读取并注入（通过CUSTOM_CHROME_CSS_ADD事件挂到主窗口）；而userstyle.css无论文件是否存在都会被读取（loadCustomCss对不存在的文件会安全返回空内容），通过CUSTOM_VIEWER_CSS_APPEND追加到渲染视图的样式表中。
• userstyle.css采用"追加"（append）语义，意味着它排在 Joplin 内置 Markdown 样式之后，可利用 CSS 层叠规则覆盖默认样式；而userchrome.css面向整个应用 UI，选择器需要针对桌面端界面结构编写。

四、编写你的第一个 userstyle.css

userstyle.css支持标准 CSS 语法，编写时直接针对渲染后的 HTML 元素写规则即可。以下示例演示了最常见的定制方向——调整阅读排版：

/* 正文字体与行高 */ .note-body { font-family: "Noto Serif SC", "Source Han Serif SC", Georgia, serif; font-size: 16px; line-height: 1.75; } /* 标题间距与配色 */ .note-body h1, .note-body h2 { color: #1f3864; border-bottom: 1px solid #e0e0e0; padding-bottom: 4px; } /* 代码块背景 */ .note-body pre { background: #f6f8fa; border-radius: 6px; padding: 12px 16px; } /* 行内代码 */ .note-body code { background: #f0f0f0; padding: 2px 4px; border-radius: 3px; }

打印注意事项：文档明确提醒，userstyle.css同时作用于笔记的屏幕显示与打印输出。因此编写时必须考虑打印效果，例如：

• 不要用"白字黑底"之类的深色背景方案，否则打印出来会浪费大量墨水，甚至因背景不打印而出现"白字看不见"的问题；
• 可考虑用@media print查询为打印单独设定样式（如去除装饰性背景、调整字号）。

五、编写你的第一个 userchrome.css

userchrome.css用于定制整个 Joplin 界面。由于它影响范围大，编写时建议先用开发者工具（DevTools）检查目标元素的 class 名，再写针对性规则。官方在设置项描述中同样将此类 CSS 视为高级功能，示例：

/* 让侧边栏更紧凑 */ .sidebar { font-size: 13px; } /* 自定义工具栏背景 */ .toolbar { background: #2d2d2d !important; color: #eee; }

需要特别说明的是：userchrome.css作用于应用界面框架，而笔记渲染区域仍由userstyle.css控制，两者互不干扰，可按需组合使用。

六、重要警告：这些是高级设置，样式可能随版本失效

官方在文档中给出了明确的免责声明，这段文字同时也被写入设置项描述（见 builtInMetadata.ts）：

userstyle.css 和 userchrome.css 是为方便使用而提供的，但它们属于高级设置，你定义的样式可能从一个版本失效到下一个版本。如果你想使用它们，请做好需要定期维护的心理准备。Joplin 团队无法承诺保持应用 HTML 结构稳定。

这意味着一件必须接受的事实：Joplin 的界面 DOM 结构不在兼容性承诺范围内。应用升级后，你依赖的某个 class 名、DOM 层级可能被重构，导致样式失效或错乱。因此：

• 升级前留意界面是否出现样式异常，必要时回到默认样式；
• 尽量使用语义明确、较稳定的选择器，减少对深层 DOM 结构的依赖；
• 为关键样式做好注释与备份，便于版本升级后快速修复；
• 若样式问题影响使用且无法快速解决，删除或重命名这两个文件即可完全恢复 Joplin 默认外观（注意重启应用使其生效）。

七、相关文档与后续阅读

• 配置界面的完整字段说明见 Configuration screen（其中 General 页面顶部显示配置目录路径）；
• 渲染引擎与 Markdown 支持范围可参考 Markdown；
• 若希望以编程方式为笔记注入自定义 HTML/CSS，可结合插件机制（见 Plugins）与插件 API 进一步定制渲染结果，其能力边界以对应插件文档为准。

小结

• userstyle.css定制渲染后的 Markdown 笔记（含打印），userchrome.css定制整个应用界面，两者都位于配置根目录，文件名固定；
• 修改后必须完全退出并重启Joplin 才生效，最小化到托盘不算退出；
• 文件路径以"配置 → General 页顶部"显示的配置目录为准，也可通过"外观"区块的两个按钮直接打开/创建；
• 两个文件均支持标准 CSS，userstyle.css以追加方式覆盖默认样式；
• 二者属高级设置，界面 DOM 结构不受版本兼容性承诺保护，需接受定期维护的现实。

【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin