Obsidian Templater 插件完整设置指南：从模板目录到用户系统命令的配置全解

Templater 是一款面向 Obsidian 的模板插件，其设置面板（Settings）决定了模板的存放位置、触发方式、自动化行为与扩展能力。本文以官方文档 docs/src/settings.md 为核心骨架，结合仓库源码（如 src/settings/Settings.ts、src/core/Templater.ts）深入剖析每一个设置项的底层实现，帮助你在读完本文后能够熟练配置模板文件夹、模板热键、文件创建自动化、启动模板、用户脚本与系统命令函数，并理解这些配置在代码层面究竟如何生效。

一、设置体系总览：全局设置与设备本地设置

在深入各项配置之前，有必要先了解 Templater 设置存储的两层结构。从源码看，Templater 的设置分为两类：

• 全局设置（Settings）：随库（vault）的 data.json 同步，所有设备共享。核心接口定义于 src/settings/Settings.ts，字段包括 templates_folder、syntax_highlighting、auto_jump_to_cursor、trigger_on_file_creation_mode、folder_templates、file_templates、command_timeout、templates_pairs、shell_path、user_scripts_folder、enabled_templates_hotkeys、startup_templates、intellisense_render 等。
• 设备本地设置（LocalSettings）：存储在浏览器 LocalStorage 中，键名为 templater-local-settings（见 src/settings/LocalSettings.ts），只对当前设备生效，必须在每台设备上分别开启。它只包含三个布尔开关：trigger_on_file_creation、enable_startup_templates、enable_system_commands（见 src/settings/LocalSettings.ts）。源码中 getLocalSettings 会先用默认值（全部为 false）与本地存储合并，见 src/settings/LocalSettings.ts。

三个设备本地开关之所以被独立出来，是因为它们都属于"危险设置"：开启后会执行不可见内容或系统命令。在设置界面切换这三个开关时，会弹出 ConfirmDangerousSettingModal 确认弹窗，其警告文案定义于 src/settings/Settings.ts。另外，Settings 接口带有 data_version: number 字段，当前为 2（见 src/settings/Settings.ts），旧版 V1 配置会在启动时通过 src/settings/migrate-settings.ts 自动迁移。

二、通用设置（General Settings）

• Template folder location（模板文件夹位置）：该文件夹内的所有文件都会作为模板出现在 Templater 的模板选择器中。对应设置键 templates_folder，默认值为空字符串 ""，即未设置时模板选择器不可用。设置界面通过 folder 类型的控件让用户选择库内目录。
• Syntax Highlighting on Desktop（桌面端语法高亮）：在编辑模式下为 Templater 命令（<% ... %>）提供语法高亮。对应键 syntax_highlighting，默认值为 true。
• Syntax Highlighting on Mobile（移动端语法高亮）：在移动端编辑模式下提供同样的高亮。对应键 syntax_highlighting_mobile，默认值为 false。官方文档特别提醒：移动端请谨慎开启，这可能会破坏移动端的 Live Preview（实时预览）。
• Automatic jump to cursor（自动跳转到光标位置）：插入模板后自动触发 tp.file.cursor，将光标移动到模板中通过 tp.file.cursor 标记的位置。对应键 auto_jump_to_cursor，默认值为 false。你也可以不开启此开关，而是通过命令面板手动执行 "Jump to next cursor location" 命令。

从源码看，语法高亮的启停是平台感知的：src/editor/Editor.ts 中 desktopShouldHighlight() 要求 Platform.isDesktopApp && syntax_highlighting，mobileShouldHighlight() 要求 Platform.isMobile && syntax_highlighting_mobile。高亮通过 CodeMirror 的 overlay 模式实现：在 JavaScript 模式之上叠加一个 templater 覆盖层，用正则 /<%<a href="https://link.gitcode.com/i/21855b27305ab942f3b01a360a30315d" target="_blank">-_]{0,1}\s*([*+]{0,1})/ 识别命令起始标签，并区分插值标签（<% %>）与执行标签（<%* %>），具体见 [src/editor/Editor.ts。值得注意的实现细节：jump_to_next_cursor_location 在 auto_jump 参数为真但设置未开启时会直接返回（见 src/editor/Editor.ts），这正是"自动跳转"开关的生效点。

此外，设置界面还有一个源码中存在的开关 Jump to note content after creating note（对应键 jump_to_cursor_after_file_name，默认 false）：从模板创建新笔记时跳过重命名提示，立即把光标移入正文。其底层逻辑位于 src/core/Templater.ts：创建笔记后若未开启此开关，则调用 active_leaf.setEphemeralState({ rename: "all" }) 触发重命名；开启后则直接聚焦编辑器。

三、模板热键（Template Hotkeys）

模板热键允许你把一个模板绑定到一个 Obsidian 命令（command），然后在 Obsidian 的 "Hotkeys"（快捷键）设置中把该命令绑定到快捷键。对应的设置入口在"Template hotkeys"页面，配置存储在 enabled_templates_hotkeys 数组中。

每个被绑定的模板会暴露两个命令，在添加或编辑热键时可以选择注册哪一个（或都注册）：

• Insert <template> 命令：将模板内容插入到当前激活文件的光标位置。底层调用 append_template_to_active_file，见 src/core/Templater.ts。
• Create <template> 命令：根据模板创建一个新笔记。底层调用 create_new_note_from_template，见 src/core/Templater.ts。

命令的注册逻辑在 src/handlers/CommandHandler.ts：命令名 Insert ${template_name} / Create ${template_name}，其中 template_name 由模板路径去掉 templates_folder 前缀和 .md 扩展名得到（见 src/handlers/CommandHandler.ts）；Insert 命令的 id 是模板路径本身，Create 命令的 id 是 create-${template_path}。每次增删热键都会调用 sync_template_hotkeys() 先注销全部旧命令再重新注册（见 src/handlers/CommandHandler.ts）。

源码还揭示了热键条目的存储格式（见 src/settings/TemplateHotkeys.ts）：enabled_templates_hotkeys 中的每个条目可以是普通字符串（模板路径）或对象 { template, insert_enabled, create_enabled }。当两个命令都启用时，serialize_template_hotkey 会把它压缩为普通字符串以保持 data.json 精简；只有禁用了某个命令时才存成对象（见 src/settings/TemplateHotkeys.ts）。resolve_template_hotkey 则负责反向规范化，并容忍手工编辑或同步导致的畸形条目（返回空模板路径，调用方会跳过），见 src/settings/TemplateHotkeys.ts。

四、文件创建自动化（File Creation）

4.1 总开关与警告

• Trigger Templater on new file creation（新文件创建时触发 Templater）：开启后 Templater 会监听 Obsidian 的 new file creation 事件，如果新文件匹配你设置的规则，就替换掉新文件内容中的所有 Templater 命令。这使 Templater 可以与日记（Daily note 核心插件）、Calendar、Review、Note refactor 等其他插件配合工作。
  • 警告：如果你创建的新文件包含未知/不安全的内容，这可能是危险的。请确保每个新文件的创建内容都是安全的。

这个开关存储在设备本地（LocalSettings.trigger_on_file_creation，默认 false），因此需要在每台设备上单独开启。

4.2 开启后出现的设置

一旦启用上述开关，以下设置变为可用：

• Excluded folders（排除文件夹）：在这些文件夹中创建的新文件永远不会触发 Templater，无论匹配模式如何。存储在 ignore_folders_on_creation 数组中。
• Template matching mode（模板匹配模式）：控制模板如何匹配新文件。对应键 trigger_on_file_creation_mode，可选值：
  • None（无）：不自动套用模板。但 Templater 仍会监听新文件创建事件，并替换新文件内容中的所有命令。
  • Folder templates（文件夹模板）：基于文件夹结构套用模板。
  • File regex templates（文件正则模板）：基于正则表达式匹配文件路径来套用模板。

4.3 底层触发链路

从源码看，完整的事件处理链路是这样的：EventHandler.setup() 在布局就绪后注册 vault.on("create", ...) 事件监听，见 src/handlers/EventHandler.ts；静态方法 Templater.on_file_creation 承担主要判断逻辑，见 src/core/Templater.ts，关键步骤包括：

1. 检查设备本地开关 trigger_on_file_creation，未开启直接返回；
2. 只处理 TFile（跳过文件夹）；非 markdown 文件在 None 模式下直接跳过；
3. 跳过模板文件夹本身：如果新文件位于 templates_folder 内（且模板文件夹不是根目录 /），不做处理，以避免同步模板文件时触发替换（见 src/core/Templater.ts）；
4. 跳过排除文件夹：遍历 ignore_folders_on_creation，路径以排除项开头的文件直接返回（见 src/core/Templater.ts）；
5. 等待 300ms 延迟（见 src/core/Templater.ts），兼容 Note extractor 等插件先写入内容的场景；
6. 如果文件正在被 Templater 自身创建（在 files_with_pending_templates 集合中），跳过，避免重复处理；
7. 非 markdown 文件只有在创建时为空（file.stat.size !== 0 则跳过）才会套用文件夹/正则模板；
8. 对于 markdown 文件，如果文件大小不超过 100,000 字节（SIZE_LIMIT），则调用 overwrite_file_commands 原地解析命令；超过该上限则跳过并输出 debug 日志（见 src/core/Templater.ts）。

五、文件夹模板（Folder Templates）

当 Template matching mode 设为 Folder templates 时显示此页面。你可以为某个文件夹及其子文件夹指定一个自动套用的模板。规则存储在 folder_templates 数组中，条目结构为 { folder: string; template: string }（见 src/settings/Settings.ts）。

关键行为：

• 最具体（最深）的匹配文件夹胜出：子文件夹的规则优先于父文件夹的规则。
• 如果需要兜底规则，请为 / 添加一条规则。
• 一条规则只适用于与其模板扩展名相同的新文件。例如，你可以为同一个文件夹分别配置笔记（.md）、bases（.base）、canvases（.canvas）或其他任何文本文件类型的规则。非 markdown 文件只有在创建时为空才会收到模板。

源码实现印证了这些行为：get_new_file_template_for_folder 从新文件所在文件夹开始，沿父级逐层向上查找，每层寻找 folder == 当前路径 且模板扩展名匹配的规则（见 src/core/Templater.ts）；扩展名匹配由 template_has_extension 判断，即模板文件的扩展名必须等于新文件的扩展名（见 src/core/Templater.ts）。在设置界面添加/编辑规则时，FolderTemplateModal 还会校验重复：同一个文件夹不能关联两个模板（见 src/settings/Settings.ts）。列表支持拖拽排序（onReorder，内部使用 arraymove），见 src/settings/Settings.ts。

六、文件正则模板（File Regex Templates）

当 Template matching mode 设为 File regex templates 时显示此页面。你可以定义正则表达式，新文件的路径会与之逐一测试。如果某个正则匹配，则自动套用与之关联的模板。规则存储在 file_templates 数组中，条目结构为 { regex: string; template: string }（见 src/settings/Settings.ts）。

关键行为：

• 规则按从上到下的顺序测试，使用第一个匹配且模板扩展名与新文件扩展名一致的规则。
• 如果需要兜底规则，请以 .* 结尾添加一条。
• 非 markdown 文件只有在创建时为空才会收到模板。

源码实现：get_new_file_template_for_file 用 new RegExp(e.regex) 对 file.path 执行 test，同时校验模板扩展名一致，返回第一个满足条件的条目（见 src/core/Templater.ts）。正则基于 JavaScript 的 RegExp 语义，建议使用 Regex101 之类的工具先验证你的正则表达式。设置界面同样支持排序与删除（见 src/settings/Settings.ts）。

七、启动模板（Startup Templates）

• Enable startup templates（启用启动模板）：开启后，Templater 启动时会自动执行已配置的启动模板。此开关存储在设备本地（LocalSettings.enable_startup_templates，默认 false），必须在每台设备上单独开启。

启动模板是在 Templater 启动时执行一次的模板，不会输出任何内容。这对于设置向 Obsidian 事件添加钩子的模板非常有用。

源码实现：execute_startup_scripts 遍历 startup_templates 数组，逐个解析模板文件并以其自身为目标文件、以 RunMode.StartupTemplate 模式解析执行（见 src/core/Templater.ts）。解析结果被丢弃（不写回文件），因此这些模板天然"不输出任何内容"。典型用途是在模板中通过 tp.hooks 之类的内部模块注册事件监听器。

八、用户脚本函数（User Script Functions）

8.1 用户脚本文件夹

• User scripts folder（用户脚本文件夹）：该文件夹中的所有 JavaScript 文件都会作为 CommonJS 模块加载，用于导入自定义的用户函数。对应键 user_scripts_folder，默认值为空字符串。该文件夹必须位于库（vault）内且可被访问。详细用法参见 用户脚本函数文档。

加载后的脚本可以通过 tp.user.<script_name>() 调用（见 用户函数总览）。脚本可以导出单个函数，也可以导出一个对象（对象的所有属性都必须是函数）；可选地，在脚本顶部使用 TSDoc 注释可以为用户脚本提供类似内置函数的智能提示体验。

8.2 用户脚本智能提示（User Script Intellisense）

• User script intellisense（用户脚本智能提示）：控制用户脚本的自动补全提示如何渲染。对应键 intellisense_render，存储为字符串枚举（见 src/settings/RenderSettings/IntellisenseRenderOption.ts）。可选值：

值	含义
0	关闭智能提示
1	渲染方法描述、参数列表和返回值（默认）
2	渲染方法描述和参数列表
3	渲染方法描述和返回值
4	仅渲染方法描述

默认值为 IntellisenseRenderOption.RenderDescriptionParameterReturn（对应 "1"），见 src/settings/Settings.ts。注意：如果脚本中没有提供对应的描述/参数/返回值信息，这些部分就不会渲染。源码中的 shouldRenderReturns / shouldRenderParameters / shouldRenderDescription 三个辅助函数分别判断某项是否应被渲染（见 src/settings/RenderSettings/IntellisenseRenderOption.ts）。当你修改此设置时，Editor.updateEditorIntellisenseSetting 会把新值同步给自动补全模块（见 src/editor/Editor.ts）。

九、用户系统命令函数（User System Command Functions）

• Enable user system command functions（启用用户系统命令函数）：开启后允许创建与系统命令关联的用户函数。此开关存储在设备本地（LocalSettings.enable_system_commands，默认 false），必须在每台设备上单独开启。
  • 警告：从未知来源执行任意系统命令可能是危险的。只运行你理解且来自可信来源的系统命令。

开启后，以下设置变为可用：

• Timeout（超时）：系统命令的最大超时时间（秒）。对应键 command_timeout，默认值为 5（见 src/settings/Settings.ts）。源码层面，设置界面会对该值做校验：必须是正数，否则提示 "Timeout must be a positive number"（见 src/settings/Settings.ts）。
• Shell binary location（Shell 二进制路径）：执行命令所用 shell 二进制的完整路径。对应键 shell_path，默认值为空字符串。可选——未指定时默认使用系统的默认 shell。所有平台上都可以使用正斜杠（/）作为路径分隔符。设置界面的输入框占位符为 /bin/bash（见 src/settings/Settings.ts）。

系统命令用户函数的使用方式参见 系统命令用户函数文档：每个函数由"函数名 + 系统命令"构成，添加后可通过 tp.user.<函数名>() 调用；可以向函数传入一个 JavaScript 对象作为参数（如 tp.user.echo({a: "value 1", b: "value 2"})），这些参数会以环境变量的形式暴露给被执行的命令（如 bash 脚本中可通过 $a、$b 访问）；系统命令内部还可以使用 Templater 内置函数——内置函数会先被替换再执行命令（例如 cat <% tp.file.path() %> 会先解析为 cat /path/to/file 再执行）。

从仓库源码看，系统命令函数以"名称-命令"二元组的形式存储在 templates_pairs: Array<<a href="https://link.gitcode.com/i/cbe90a95b03fe7d4b3055d6284241bd7" target="_blank">string, string]> 中（见 [src/settings/Settings.ts），设置界面通过 SystemCommandModal 添加/编辑，并校验函数名不得重复（"This function name is already in use"，见 src/settings/Settings.ts）。用户函数的统一调用入口是 tp.user 对象，由 src/core/functions/user_functions/UserFunctions.ts 与 src/core/functions/user_functions/UserSystemFunctions.ts 负责生成；需要说明的是，用户函数目前不支持 Obsidian 移动端（见 用户函数总览）。

十、设置页面的代码组织与维护提示

Templater 的设置界面由 TemplaterSettingTab 类实现（继承自 Obsidian 的 PluginSettingTab），全部定义在 src/settings/Settings.ts 中。它使用 Obsidian 新版的 getSettingDefinitions 声明式 API 组织页面，按分组（group）依次呈现：通用设置、语法高亮、文件创建、启动模板、用户脚本、用户系统命令（见 src/settings/Settings.ts）。

几个值得注意的工程细节：

• 设置面板会监听 vault 的 create / delete / rename 事件并防抖刷新（debounce(..., 200, true)），确保模板文件夹变化时列表即时更新（见 src/settings/Settings.ts）。
• 由于 Obsidian 的 page-row 处理会在捕获阶段拦截点击，设置页对包含 href 的点击目标在捕获阶段调用了 e.stopPropagation()，保证文档外部链接可正常打开（见 src/settings/Settings.ts）。
• 当修改某些设置（如 trigger_on_file_creation、trigger_on_file_creation_mode、enable_startup_templates、enable_system_commands）时，会触发整页重渲染（rerenderKeys），以动态显示/隐藏对应的设置子页面（见 src/settings/Settings.ts）。
• 旧版设置（V1）会在迁移时把 enable_folder_templates / enable_file_templates 两个布尔开关合并为 trigger_on_file_creation_mode 的 "folder" / "regex" 值，并对 folder_templates、file_templates、templates_pairs、enabled_templates_hotkeys 做过滤清洗，相关实现见 src/settings/migrate-settings.ts。

十一、常见配置组合建议

以下配置组合可以直接在设置面板中落地，用于最常见的自动化场景：

1. 模板库 + 手动插入：设置"Template folder location"为你的模板目录，开启"Automatic jump to cursor"；插入模板后光标自动定位到 tp.file.cursor 标记处。
2. 新笔记自动套模板（文件夹模式）：开启设备本地开关"Trigger Templater on new file creation"，将"Template matching mode"设为 Folder templates，然后为 / 添加一条兜底规则指向默认笔记模板；如需细分，再为子文件夹分别添加 .md 模板。
3. 正则驱动的分类模板：将匹配模式改为 File regex templates，例如用 .*\/日记\/.* 匹配日记目录下的文件并关联日记模板，最后用 .* 兜底。
4. 启动时挂载事件钩子：开启设备本地开关"Enable startup templates"，添加一个只包含 tp.hooks 相关命令、不输出任何内容的启动模板。
5. 扩展自定义能力：设置"User scripts folder"加载 CommonJS 脚本（桌面端），按需开启"Enable user system command functions"并配置 command_timeout 与 shell_path 以运行外部命令。

最后提醒两点：凡是带有"stored on this device only"提示的开关（文件创建触发、启动模板、系统命令），在更换设备或使用 Obsidian Sync 同步配置时都不会自动同步开启，需要在新设备上手动确认；而 data_version 为 2 的全局配置则会在首次加载时由迁移逻辑自动升级，无需手工干预。