思源笔记 v3.1.23 版本深度解析编辑器细节增强、环境变量配置与内核导出 API 改进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记SiYuanv3.1.23 是一个以“细节打磨”为核心的版本围绕编辑器交互、数据库、搜索定位、导出能力与部署方式进行了 40 余项增强与修复。本文以官方更新日志为骨架结合仓库源码app/src前端与kernel内核逐一剖析关键改动背后的实现原理帮助开发者和深度用户理解这些细节变化如何落地并掌握通过环境变量定制部署、通过内核 API 获取标准 Markdown 内容等实战技能。版本概览本版本定位为“Improves some details”细节优化版主要包含 43 项增强Enhancement、10 项缺陷修复Bugfix、2 项依赖重构Refactor与 1 项内核 API 改进Development。整体改动覆盖四类主题编辑器与内容块交互代码/kbd/tag 元素编辑、标题块复制粘贴、表格只读复制、代码块解析、RTL/LTR 排版切换快捷键等数据库属性视图体验主键 emoji 居中换行、日期字段相对筛选、属性面板链接打开、居中/右对齐后的入口块图标点击等搜索与定位表格与最近块搜索定位、退出聚焦后的定位、反向提及高亮等部署与运维通过环境变量设置访问授权码、工作空间路径与语言内核 APIexportMdContent能力增强HarmonyOS Next 内核改为后台任务等。一、编辑器与内容块交互增强1.1 行内元素编辑与菜单补全本版本集中改进了代码code、键盘kbd、标签tag三类行内元素的编辑体验对应 Improve code/kbd/tag element editing并在/菜单中新增了 kbd 元素入口对应 Issue 14139。这意味着用户现在可以通过斜杠菜单快速插入键盘键位标记元素用于记录快捷键组合或操作提示行内元素在编辑、选中、删除时的行为也更为一致。1.2 标题块复制粘贴与文档标题净化标题块复制粘贴优化Issue 14114复制带有子内容的标题块并粘贴时层级与内容结构能够被正确保留不再出现错位。移除文档标题中的brIssue 14057文档标题HPath 所对应的文档名中不再允许保留br换行标签避免标题渲染异常。1.3 表格交互点击隐藏工具栏与只读复制点击表格内部时会自动隐藏块工具栏Issue 14098减少对表格编辑的遮挡。阅读模式只读模式下支持复制表格Issue 14080此前只读模式下表格无法直接选中复制本版本补齐了这一能力。1.4 代码块解析与查找替换细节代码块解析改进Issue 14116涉及代码块中特殊字符与语言标记的解析边界。图片/链接元素的查找替换Issue 14049查找替换现在可以正确处理图片与链接元素而非仅文本。含转义字符文本的查找替换Issue 14173对包含转义字符如\n、\的文本进行查找替换时结果不再出现错乱。1.5 粘贴行为调整拖入多个文档插入列表引用Issue 13942将多个文档拖入编辑器时会以列表引用的形式插入便于批量引用整理。文本中间含不再创建引用块Issue 14162粘贴形如foo bar的文本时不再因中间的误触发 blockquote 块转换。菜单粘贴改进Issue 14112右键菜单中粘贴的格式处理更为稳健。二、数据库属性视图体验优化数据库在 v3.1.23 中获得多项针对性优化数据库居中/右对齐后入口块图标无法点击Issue 13853当数据库属性视图整体居中或右对齐时行首的入口块图标仍可正常点击进入文档。主键 emoji 居中与换行Issue 13940数据库主键列中的 emoji 现在能够正确居中并且支持按宽度换行不再溢出或截断。日期字段“相对介于”筛选Issue 14091日期字段的筛选条件新增“相对介于”支持可基于相对时间区间如“最近 N 天”进行过滤。属性面板 - 数据库链接打开优化Issue 14104在属性面板中点击数据库关联链接时跳转与打开行为更稳定。从收件箱移动后展开文档树 / 复制文档后展开文档树Issue 14097 与 Issue 14125文档树会自动展开到目标位置方便确认移动/复制结果。三、搜索、定位与引用3.1 定位与聚焦体验表格与最近块搜索定位改进Issue 13876在全局搜索与最近块搜索结果中表格块能够被精准定位到对应单元格。退出聚焦后定位改进Issue 13897从聚焦模式Focus退出后光标与视图位置能够恢复到合理区域。展开标题后显示引用计数Issue 14169标题展开后其下内容块的引用计数能够及时刷新显示。3.2 引用与反向提及容器块反向链接去重Issue 13872容器块如列表、引述块的反向链接不再重复计数。反向提及高亮改进Issue 14103反向提及面板中的关键词高亮更准确。块引用计数刷新改进Issue 14109编辑后引用计数刷新时机更及时。文档转为标题后刷新虚拟引用缓存Issue 14147将文档转换为标题块后虚拟引用缓存会立即重建避免陈旧结果。嵌入块中最后非文档路径的文本隐藏Issue 13866嵌入块Embed的面包屑中最后一段非文档路径的文本不再显示避免歧义。3.3 网络图片与分享细节收件箱中隐藏网络图片图标Issue 14084收件箱列表中不再显示网络图片的缩略图图标列表更清爽。分享到社区时仅转换引用为文本Issue 14100。四、快捷键自定义AI 写作与 RTL/LTR 切换本版本为两个高频操作开放了自定义快捷键能力前端按键分发与后端配置结构均已就绪。4.1AI writing支持自定义快捷键此前 AI 写作只能通过斜杠菜单或工具栏触发v3.1.23 起可以在「设置 → 快捷键 → 编辑器 → AI 写作」中自定义触发键Issue 13894。从前端实现看快捷键默认值与自定义值统一登记在app/src/constants.ts的 keymap 结构中// app/src/constants.ts ltr: {default: , custom: }, aiWriting: {default: , custom: },按键分发位于 键盘事件处理当事件命中keymap.editor.general.aiWriting.custom配置且非按键重复!event.repeat时调用AIChat(protyle, nodeElement)唤起 AI 聊天窗口if (!event.repeat matchHotKey(window.siyuan.config.keymap.editor.general.aiWriting.custom, event)) { event.preventDefault(); event.stopPropagation(); AIChat(protyle, nodeElement); return; }同时斜杠菜单中 AI 写作项也会读取该自定义快捷键并显示为提示hint 扩展实现。4.2 内容块 LTR/RTL 布局切换支持自定义快捷键对于需要混合编辑阿拉伯语、希伯来语与中文/英文内容的用户本版本将「内容块 LTR/RTL 布局切换」也开放为可自定义快捷键Issue 14113。对应的按键处理同样位于 keydown.ts命中editor.general.rtl.custom时批量设置选中块的direction: rtl命中editor.general.ltr.custom时批量设置direction: ltrif (matchHotKey(window.siyuan.config.keymap.editor.general.rtl.custom, event)) { let selectElements: HTMLElement[] Array.from(protyle.wysiwyg.element.querySelectorAll(.protyle-wysiwyg--select)); if (selectElements.length 0) { selectElements [nodeElement]; } updateBatchTransaction(selectElements, protyle, (e: HTMLElement) { e.style.direction rtl; }); event.stopPropagation(); event.preventDefault(); return; }需要说明的边界条件属性视图NodeAttributeView、代码块NodeCodeBlock与数学公式块NodeMathBlock不支持该切换见 gutter 菜单实现。此外全局编辑器的 RTL 开关editor.rtl仍然保留可通过「设置 → 编辑器」开启开启后会在.protyle元素上添加.rtl类名便于主题开发者针对 RTL 布局定制样式见 protyle 初始化。五、环境变量配置授权码、工作空间与语言本版本通过两个 Pull Request14142 与 14148将「访问授权码」「工作空间路径」「界面语言」三个关键参数开放为环境变量方式配置极大方便了 Docker 与脚本化部署。5.1 三个新增环境变量环境变量作用对应命令行参数SIYUAN_ACCESS_AUTH_CODE设置访问授权码Access Auth Code--accessAuthCodeSIYUAN_WORKSPACE_PATH设置工作空间路径--workspaceSIYUAN_LANG设置界面语言--lang支持的SIYUAN_LANG取值与 语言文件目录 一致包括ar/de/en/es/fr/he/hi/id/it/ja/ko/nl/pl/pt-BR/ru/sk/th/tr/uk/zh-CN/zh-TW。5.2 底层实现命令行参数与环境变量的回退逻辑内核在 working.go 中实现了coalesceToEnvVar当命令行参数为空时回退到同名环境变量func coalesceToEnvVar(fromCLI *string, envVarName string) *string { if fromCLI nil || *fromCLI { ret : os.Getenv(envVarName) return ret } return fromCLI }该回退仅对默认值为空字符串的参数生效--workspace、--accessAuthCode、--lang而--port、--readonly、--mode等带有明确默认值的参数不会读取环境变量见 BootWithFlagsworkspacePath *coalesceToEnvVar(workspacePath, SIYUAN_WORKSPACE_PATH) accessAuthCode *coalesceToEnvVar(accessAuthCode, SIYUAN_ACCESS_AUTH_CODE) lang *coalesceToEnvVar(lang, SIYUAN_LANG)授权码在赋值后会经过RemoveInvalid与TrimSpace清理working.go语言值则通过LangToBCP47兼容历史下划线写法如zh_CN→zh-CN见 working.go。5.3 容器部署的强制校验与旁路开关一个容易踩坑的细节Docker 容器中必须显式设置访问授权码。在 BootWithFlags 中若检测到容器环境RunInContainer且授权码仍为空内核会输出提示并直接以安全风险码退出if RunInContainer { if AccessAuthCode { if SiYuanAccessAuthCodeBypass { interruptBoot false fmt.Println(bypass access auth code check since the env [SIYUAN_ACCESS_AUTH_CODE_BYPASS] is set to [true]) } if interruptBoot { fmt.Printf(the access authorization code command line parameter (--accessAuthCode) must be set when deploying via Docker ) os.Exit(logging.ExitCodeSecurityRisk) } } }如果确实需要在容器中跳过空授权码检查例如仅本机临时调试可以设置SIYUAN_ACCESS_AUTH_CODE_BYPASStrue该变量在 initEnvVars 中解析但生产环境不建议使用。5.4 实战示例环境变量方式启动适用于 Docker 与脚本化部署export SIYUAN_WORKSPACE_PATH/data/siyuan export SIYUAN_ACCESS_AUTH_CODEyour-secret export SIYUAN_LANGzh-CN # 然后启动内核或桌面应用对应的内核进程命令行参数方式等价示例kernel --workspace/data/siyuan --accessAuthCodeyour-secret --langzh-CN两者优先级为命令行参数优先未设置时才回退到环境变量。六、内核 APIexportMdContent改进v3.1.23 的 Development 分类下改进了内核 APIexportMdContentIssue 14032该 API 用于按块 ID 获取标准 Markdown 内容是「复制为标准 Markdown」「复制文档」等功能的后端支撑。6.1 接口注册与权限路由注册位于 router.go采用 POST 方式并需要登录与管理员角色ginServer.Handle(POST, /api/export/exportMdContent, model.CheckAuth, model.CheckAdminRole, exportMdContent)6.2 请求参数处理器实现在 export.go请求参数如下参数类型必填说明idstring是文档或内容块 ID会经过InvalidIDPattern校验refModeint否内容块引用导出模式默认取导出设置Export.BlockRefModeembedModeint否内容块嵌入导出模式默认取导出设置Export.BlockEmbedModeyfmbool否是否在文档开头添加 YAML Front Matter默认 truefillCSSVarbool否是否填充 CSS 变量导出为 HTML 场景adjustHeadingLevelbool否是否调整标题层级imgTagbool否是否使用img标签输出图片addTitlebool否是否在导出内容顶部添加文档标题默认取导出设置Export.AddTitle其中refMode的取值语义见 导出配置2为锚文本块链、3为仅锚文本、4为块引转脚注 锚点哈希默认0原始文本与1Blockquote以及5锚点哈希已在历史版本中废弃。embedMode取0原始文本或1Blockquote默认。6.3 调用链与核心实现API 处理器会先解析并合并导出设置再调用 ExportMarkdownContent。该函数在导出读锁的保护下获取块树treenode.GetBlockTree调用exportMarkdownContent0完成导出转换最后按addYfm决定是否前置 YAML Front Matteryfm(docIAL)其中 IAL 来自文档根块的 KramdownIALtree : prepareExportTree(bt) hPath tree.HPath exportedMd exportMarkdownContent0(id, tree, , false, adjustHeadingLv, imgTag, .md, refMode, embedMode, Conf.Export.FileAnnotationRefMode, ...) docIAL : parse.IAL2Map(tree.Root.KramdownIAL) if addYfm { exportedMd yfm(docIAL) exportedMd }在更底层的exportMarkdownContent0中export.go可以观察到若干本版本相关的导出细节非表格中的br /节点在导出 Markdown 时会替换为\n文本节点与 6.1 中「文档标题移除br」相呼应adjustHeadingLv为 true 时调用adjustHeadingLevel统一调整标题层级社区图床导出场景assetsDestSpace2Underscore会把资源链接中的空格转换为下划线同步处理链接地址、iframe/audio/video的资源src。响应数据结构为{ code: 0, data: { hPath: 20210808180117-6v0mkxr/20200923234011-ieuun1p.sy, content: # 导出的 Markdown 正文... } }6.4 前端实际调用示例前端「复制为标准 Markdown」菜单项通过该 API 获取内容并写入剪贴板commonMenuItem.tsconst response await fetchSyncPost(/api/export/exportMdContent, { id: stdMarkdownId, refMode: 3, embedMode: 1, yfm: false, fillCSSVar: false, adjustHeadingLevel: false }); const text response.data.content; writeText(text);「复制文档」功能则并行调用exportMdContent与getBlockDOM将纯文本 Markdown 与带data-siyuan属性的 HTML 同时写入剪贴板实现粘贴到思源内保留块结构、粘贴到外部得到标准 Markdown 的双重效果openTitleMenu.ts。七、其他增强与重构7.1 窗口与界面细节图表面板全屏后窗口控制按钮位置修正Issue 13899。外观模式亮/暗切换改进Issue 14157。动态加载Dynamic loading改进Issue 14004。双击.search__drag恢复默认宽度Issue 13964搜索面板拖拽分隔条可一键复位。嵌入块面包屑优化、浏览器剪藏扩展改进Issue 14105等。7.2 依赖与运行环境重构Graphviz 升级至 v3.11.0Issue 13852影响图表生成与导出质量。Electron 升级至 v33.4.1Issue 14101桌面端获得 Chromium 引擎的稳定性与安全修复。HarmonyOS Next 内核改为后台任务Issue 14131移动端/鸿蒙端内核生命周期管理更符合系统规范。资源插入大小上限从 4G 调整为 8GIssue 14188允许插入更大的附件资源。八、本版本缺陷修复清单以下为本版本修复的 10 个问题多数与上述增强相互配套问题修复要点Windows 10 上行内代码异常修复行内代码在 Windows 10 上的渲染/输入异常属性面板关系字段异常修复数据库关系字段在属性面板中的显示与交互异常错误的进程名修正内核进程命名移动端缺少 mermaid 编辑入口移动端补齐 mermaid 图编辑入口滚动条样式错误修正滚动条样式导入 Markdown 文件夹时相对路径基准错误导入文件夹时资源相对路径以错误的基准目录构造移动文档后回滚文档异常修复移动后历史回滚的异常macOS/Linux/Windows arm64 未打包字体目录arm64 平台安装包补齐字体资源无法下载在线视频修复网络视频下载失败dragover__bottom 类名未移除拖拽悬停样式类残留未清理九、升级与获取v3.1.23 属于 v3.1.x 系列的一个维护版本建议所有 v3.1.x 用户平滑升级。官方渠道提供桌面端、移动端与服务端安装包详见仓库内的 更新日志目录 与其他版本的 变更记录 对比。对于部署者建议结合本版本新增的环境变量能力将授权码、工作空间路径与语言通过环境变量注入容器或 systemd 服务避免明文参数出现在进程列表中对于开发者可通过/api/export/exportMdContent构建文档导出、同步、备份等周边工具实现基于思源内核的二次开发。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考