思源笔记 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 版本的变更记录展开系统梳理该版本在编辑器交互、数据库属性视图、导入导出、搜索定位等方面的功能改进与缺陷修复并结合当前仓库源码深入解析环境变量配置机制、exportMdContent内核 API 以及 RTL/LTR 排版等关键实现。读完本文你将能完整掌握 v3.1.23 的功能全貌、升级要点以及如何在 Docker 与 CLI 场景下利用环境变量完成无界面化配置。版本概述一次面向细节的体验优化思源笔记 v3.1.23 是一个以改进细节为主题的维护版本。从变更记录看该版本没有引入全新的重磅功能而是把重心放在了三类工作上编辑器交互打磨涉及代码、键盘、标签元素的编辑体验以及标题块、代码块的复制粘贴行为数据库属性视图完善包括整体居中/居右后的块标点击、主键表情的居中与换行、日期字段相对过滤等基础设施升级与自动化配置Graphviz 与 Electron 版本升级以及支持通过环境变量设置授权码、工作空间路径与界面语言。其中环境变量配置能力与exportMdContent内核 API 的改进对开发者与自托管部署用户价值最大后文将结合源码展开说明。功能改进编辑器、数据库与搜索的细节打磨该版本共包含 41 项功能改进可按主题划分为以下几组。数据库属性视图相关改进数据库是思源笔记的块级二维表格组织能力v3.1.23 对它做了多处细节修正修复数据库整体居中或居右后无法点击项目块标的问题改进数据库主键中表情的居中与换行显示改进属性面板中数据库链接的打开方式改进数据库日期字段的相对过滤如最近 N 天这类相对时间判断。这些改动集中在内核的kernel/av/目录属性视图布局、过滤、排序实现与前端app/src/的属性面板模块涉及块标的点击命中区域、表情渲染的 CSS 排版以及 SQL 过滤条件的计算逻辑。编辑器编辑与复制粘贴改进代码/键盘/标签元素编辑改进这三种行内元素的编辑体验同时/菜单新增键盘元素入口方便快速插入kbd样式元素代码块解析改进代码块在粘贴与转换场景下的解析健壮性标题块复制与粘贴改进标题块在复制粘贴时的结构与属性保留粘贴行为优化粘贴中间包含的文本时不再自动创建引述块避免误触发块级转换文档标题清理删除文档标题中的br标签避免标题被强行换行只读模式复制表格在只读模式下允许直接复制表格内容文件拖拽插入将多个文件拖拽到编辑器时以列表形式插入引用而不是平铺成多个段落。搜索、定位与反向链接表格与最近块搜索的定位改进搜索结果在表格块、最近打开块列表中的定位精度查找替换增强支持对图片元素与链接元素的查找替换并改进包含转义符文本的搜索替换反向链接去重与高亮对容器块的反向链接进行去重改进反向提及反链的高亮效果块引用计数刷新改进块引用计数在不同场景下的实时刷新包括展开折叠的标题后立即显示块引用计数。面包屑、文件树与文档移动隐藏嵌入块中最后一个非文档路径的面包屑文字减少冗余路径信息从收集箱移动文档后自动展开文件树对应节点复制文档后同样自动展开文件树文档转换标题后刷新虚拟引用缓存回溯文档回到引用来源后同步更新大纲移动文档后修复回溯文档异常。界面、主题与多语言改进退出对焦后的光标与滚动定位改进关系图面板全屏后窗口控制按钮的位置改进外观模式明亮/暗黑切换时的过渡细节改进市集Bazaar主题更新流程改进动态加载dynamic loading性能改良 RTL从右到左渲染支持在表格内点击时隐藏工具条。资源上传与剪藏插入资源文件大小限制由 4G 调整为 8G前端上传配置中对应的最大文件大小也随之调整。从 Options.ts 的默认上传配置可以看到上传参数通过upload.max控制字段名为file[]并会对文件名中的非法字符做清洗改进浏览器剪藏扩展的抓取与写入行为隐藏收集箱Inbox中的网络图标。快捷键扩展v3.1.23 为两类操作新增了自定义快捷键支持AI 编写支持自定义快捷键可以在快捷键设置中为 AI 续写/编写操作绑定自定义按键内容块 LTR/RTL 布局切换支持自定义快捷键从 protyle/gutter/index.ts 的菜单实现可以看到块级菜单中内置了ltr与rtl两个动作分别对表格、HTML 块及普通块设置direction样式这两个动作读取window.siyuan.config.keymap.editor.general.ltr/rtl.custom作为快捷键加速键即默认快捷键与自定义快捷键统一走 keymap 配置体系。与此同时appearanceTab.ts 提供了编辑器级 RTL 开关editor.rtl两者形成全局默认方向 单块方向覆盖的完整排版方案。缺陷修复跨平台兼容与渲染修正该版本修复了 10 个缺陷其中值得关注的有Windows 10 上的行级代码显示异常修复 Windows 10 系统中行内代码行级代码样式错乱的问题属性面板关联字段异常修复属性视图中关联字段的取值与刷新问题错误进程名称修复任务管理器中显示错误进程名称的问题移动端缺少编辑 Mermaid 入口补齐移动端 Mermaid 图的编辑入口导入 Markdown 文件夹时相对路径错误修复批量导入 Markdown 时资源相对路径解析错误对应导入逻辑位于 kernel/model/import.go滚动条样式不正确修复滚动条在不同主题下的样式问题macOS/Linux/Windows arm64 未打包字体修复三个平台 arm64 架构发行包中字体文件缺失的问题确保 JetBrains Mono、霞鹜文楷等内置字体见 appearance/fonts在 arm64 设备上可用网络视频无法下载修复剪藏网络视频资源时的下载失败dragover__bottom类名未移除修复拖拽插入时残留样式类名导致后续排版异常的问题。开发重构依赖升级Graphviz v3.11.0本版本将 Graphviz 升级至 v3.11.0。Graphviz 用于渲染思维导图与流程图内核侧通过 kernel/util/ 下的相关工具调用 dot 命令升级后带来更稳定的图形渲染与更完善的语法支持。Electron v33.4.1桌面端将 Electron 升级至 v33.4.1对应打包配置见 electron-builder.yml 及各平台配置文件。该升级主要带来 Chromium 内核的稳定性与安全修复建议桌面端用户及时更新。开发者改进内核 APIexportMdContentv3.1.23 对内核 APIexportMdContent进行了改进。该 API 位于 kernel/api/export.go作用是将指定文档块导出为 Markdown 文本内容。从源码看其请求参数与行为如下参数类型说明idstring必填文档块 ID会经过util.InvalidIDPattern校验refModeint块引用导出模式默认取model.Conf.Export.BlockRefModeembedModeint嵌入块导出模式默认取model.Conf.Export.BlockEmbedModeyfmbool是否输出 YAML Front Matter默认truefillCSSVarbool是否填充 CSS 变量adjustHeadingLevelbool是否调整标题层级imgTagbool是否输出img标签addTitlebool是否在导出内容前添加文档标题默认取model.Conf.Export.AddTitle响应数据为{ code: 0, data: { hPath: 文档的人类可读路径, content: 导出的 Markdown 内容 } }该 API 常被插件与自动化脚本用于以 Markdown 形式取回文档内容配合refMode/embedMode可以控制引用与嵌入在导出时的展开策略是构建外部工作流如同步到其他系统、喂给 LLM 处理的重要入口。部署新能力环境变量配置授权码、工作空间与语言v3.1.23 引入了三项通过环境变量进行配置的能力对 Docker 与无人值守部署场景尤其有用。其实现位于 kernel/util/working.go 的BootWithFlags函数内核启动时通过coalesceToEnvVar实现命令行参数为空则回退到环境变量的统一策略。SIYUAN_ACCESS_AUTH_CODE授权码当未通过命令行--accessAuthCode指定授权码时内核会读取环境变量SIYUAN_ACCESS_AUTH_CODE作为访问授权码。该变量在 Docker 容器场景下尤为重要内核在容器中启动时如果授权码为空且未设置SIYUAN_ACCESS_AUTH_CODE_BYPASStrue会直接拒绝启动见 working.go。因此 Docker 部署必须显式提供授权码docker run -e SIYUAN_ACCESS_AUTH_CODEyour-code -p 6806:6806 b3log/siyuan对应的 Docker 入口脚本 entrypoint.sh 还支持通过SIYUAN_WORKSPACE_PATH或--workspace参数指定工作空间并自动处理PUID/PGID用户权限。SIYUAN_WORKSPACE_PATH工作空间路径当未通过--workspace指定工作空间时内核会读取SIYUAN_WORKSPACE_PATH环境变量若仍为空则回退到默认路径~/SiYuanmacOS 下为~/Library/Application Support/SiYuan。工作空间路径还会被写入~/.config/siyuan/workspace.json以便下次启动时自动恢复见 working.go。值得注意的是kernel/cli/cmd/root.go 中 CLI 子命令同样遵循命令行参数优先、SIYUAN_WORKSPACE_PATH次之、默认路径兜底的解析顺序说明该环境变量同时作用于服务模式与 CLI 模式。SIYUAN_LANG界面语言未通过--lang指定语言时读取SIYUAN_LANG环境变量。内核会把值转换为 BCP-47 格式如zh_CN会自动转为zh-CN支持的语言代码与仓库 app/appearance/langs 目录下的语言包一致包括ar、de、en、es、fr、he、hi、id、it、ja、ko、nl、pl、pt-BR、ru、sk、th、tr、uk、zh-CN、zh-TW。组合使用示例SIYUAN_ACCESS_AUTH_CODEsecret SIYUAN_WORKSPACE_PATH/data/siyuan SIYUAN_LANGzh-CN ./kernel --port6806三个环境变量的优先级统一为命令行参数 环境变量 默认值这一回退逻辑保证了桌面端、Docker 端与 CLI 三种启动方式行为一致。鸿蒙端适配内核改为长时任务v3.1.23 还针对鸿蒙HarmonyOS系统做了一项重要适配——将内核改为长时任务运行。鸿蒙系统对后台进程有严格的调度限制普通任务可能被系统挂起或回收改为长时任务后可以保证内核在后台持续提供服务避免笔记数据同步与索引中断。内核中鸿蒙端专属适配代码位于 kernel/harmony/kernel.go。升级建议与注意事项综合来看v3.1.23 是一个稳中有进的维护版本建议按以下方式规划升级桌面端用户直接通过应用内更新或官方发布渠道升级重点体验编辑器细节改进与 Electron 升级带来的稳定性提升Docker / 服务器部署用户升级后可利用SIYUAN_ACCESS_AUTH_CODE、SIYUAN_WORKSPACE_PATH、SIYUAN_LANG三个环境变量简化容器编排配置如 docker-compose 环境变量段替代原来的启动参数arm64 设备用户Apple Silicon、树莓派等建议优先升级以修复此前未打包字体导致的界面字体缺失问题插件与脚本开发者关注exportMdContentAPI 的参数与返回结构变化如有调用需回归测试大文件用户上传资源大小上限由 4G 提升至 8G超大视频、数据集等资源可以直接入库管理。由于 v3.1.x 系列后续仍有迭代当前仓库内核版本已演进至 kernel/util/working.go 中声明的 v3.7.2建议在升级前备份工作空间并查阅 CHANGELOG.md 与 app/changelogs 目录下的逐版本记录确认从当前版本到目标版本的完整变更路径。【免费下载链接】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），仅供参考