企业官网建设流程全解析

SiYuan v3.5.4 版本解析：导出管线、编辑器交互与安全机制的深度改进

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

SiYuan v3.5.4 是一次以「细节打磨」为基调的例行版本，围绕文档导出（尤其是 Word/.docx 与 Pandoc 管线）、编辑器输入行为、数据视图（数据库）功能、同步安全与桌面端运行时五大主线做了系统性改进。本文基于仓库中的 v3.5.4 繁体中文变更日志 全文展开，逐项梳理本版本引入的能力与修复，并结合 kernel 端 Go 内核与 app/src 端前端源码，说明这些改进背后的实现位置与工作机制，帮助开发者与维护者理解 SiYuan 在导出链路、安全防护与跨平台打包上的工程实践。

版本概览

v3.5.4 官方将其定位为「改进了某些细节」的版本，变更分为三类：

• 改进功能（31 项）：覆盖导出、编辑器、数据库、安全、平台适配；
• 修复缺陷（6 项）：涵盖 iOS 滚动、页签图标、快照页卡死、编辑器选中、标题批量转换与一处任意文件读取漏洞；
• 开发重构（1 项）：桌面端运行时升级至 Electron v39.3.0。

下文按主题分组完整继承变更日志中的全部条目，并对关键条目给出仓库内的源码级佐证。

导出管线：Pandoc、.docx 与 .sy.zip

导出是 v3.5.4 改动最集中的模块，变更日志中直接相关的条目包括：

• 新增导出设置：包含子文件、包含关联文件；
• 支持多選文件匯出 .sy.zip；
• 改進匯出為 Word .docx 的功能；
• 在匯出設定中新增「從資源名稱移除 ID」開關；
• 改進資料庫資源欄位的圖片匯出尺寸；
• 匯出資料庫為CSV 時包含關聯資源；
• 改進 Microsoft Excel 相容性；
• 支援為匯出 docx設定 Pandoc 參數；
• 內建 Pandoc 匯出 .docx 範本；
• 填入 Base64 後，圖片網址列會自動轉換為資源。

从源码结构看，这些能力落在内核的两条链路上：

1. 模板与资源解析。InitPandoc()负责定位随发行版分发的模板文件：模板.docx优先在工作区目录查找pandoc-resources/pandoc-template.docx，找不到时回退到内置的 pandoc 资源目录——该目录下确实存放了 pandoc-template.docx 与 pandoc_color_filter.lua 两个文件，分别对应「内建 Pandoc 导出 .docx 模板」与导出时保留颜色的过滤器。相关全局变量定义于 kernel/util/pandoc.go：

   var ( PandocBinPath string // Pandoc 可执行文件路径 PandocTemplatePath string // Pandoc Docx 模板文件路径 PandocColorFilterPath string // Pandoc 颜色过滤器路径 )

2. 可自定义的 Pandoc 参数。变更日志中「支援為匯出 docx 設定 Pandoc 參數」对应的是通用转换接口 kernel/api/pandoc.go：该接口接收dir（输出子目录）与args（完整的 Pandoc 命令行参数数组），最终交由 ConvertPandoc 执行。执行时会在工作区temp/convert/pandoc/<dir>下创建临时目录并将 Pandoc 的工作目录设定为该目录，转换成功后返回以/开头的相对路径供前端取回产物：

   func ConvertPandoc(dir string, args ...string) (path string, err error) { if "" == PandocBinPath || ContainerStd != Container { err = ErrPandocNotFound return } pandoc := exec.Command(PandocBinPath, args...) // ... pandoc.Dir = absPath output, err := pandoc.CombinedOutput() // ... }

   值得注意的是其「内置优先 + 自定义覆盖」策略：InitPandoc()会先检查工作区配置conf.json中的export.pandocBin，若用户已显式指定自定义 Pandoc 路径（且不是工作区临时目录内的副本），则直接使用自定义版本；否则按平台/架构（Windows amd64、macOS amd64/arm64、Linux amd64/arm64）从 app/pandoc 下的平台 zip 包解压出内置二进制。IsValidPandocBin还会校验候选二进制的文件魔数（ELF、Mach-O、PE「MZ」、FAT）并拒绝 shebang 脚本，最后以--version输出确认真实可用——这与「改進匯出為 Word .docx」的稳定性目标直接相关。

此外，「包含子文件 / 包含关联文件」两个导出开关、「从资源名称移除 ID」开关，属于导出对话框中控制产物范围的设置：前者决定导出单篇文档时是否级联打包其子树与反向关联文档，后者用于在导出时把资源文件名中的 SiYuan 块 ID 前缀（形如20240101120000-abc123）剥离，使导出的.md/.docx配套资源目录对外部工具更友好。「多選文件匯出 .sy.zip」则把原本单文档的「打包为 .sy.zip」能力扩展到批量场景，多个.sy文件及其资源会被合并进同一个压缩归档。「匯出資料庫為 CSV 時包含關聯資源」与「資料庫資源欄位的圖片匯出尺寸」两项则针对数据视图（AV）：前者保证 CSV 中引用的附件随导出产物一并落地，后者修正了资源字段图片在导出产物中的尺寸渲染问题。

编辑器交互与输入行为

v3.5.4 对编辑体验的改进集中在「触发器行为」与「块级操作」两类：

• 改進提示、清單和標題的嵌套編輯；
• 改進輸入{{、/或#及貼上行為；
• 塊超連結支援fullscreen=1以實現全螢幕顯示；
• 改進游標在表格單元格內的縱向移動；
• 支援使用Alt+Enter 開啟提示塊對話框；
• 支援MLIR 程式碼塊語法高亮；
• 改進在複製 PDF 標註後「以純文字貼上」的功能；
• 改進瀏覽器剪藏擴充功能對 MathJax 公式的支援。

其中「塊超連結支援 fullscreen=1」的实现可以在前端找到对应逻辑：编辑器全屏入口 app/src/protyle/breadcrumb/action.ts 中，fullscreen()通过切换fullscreenCSS 类完成进入/退出，并处理多个编辑实例之间全屏状态的互斥：

export const fullscreen = (element: Element, btnElement?: Element) => { // ... const isFullscreen = element.className.includes("fullscreen"); if (isFullscreen) { element.classList.remove("fullscreen"); } else { element.classList.add("fullscreen"); } // 遍历其他编辑器实例，退出它们的全屏状态 ... };

块超链接在 URL 查询串中携带fullscreen=1时，目标文档加载后会自动走这条全屏路径，适合把某个块嵌入演示或监控大屏场景。「提示块（callout）Alt+Enter 打开对话框」则补齐了纯键盘操作链路：在提示块内按 Alt+Enter 即可弹出属性对话框，而无需鼠标点击菜单。触发器类改进（{{、/、#与粘贴行为）针对的是输入防抖与候选面板的时序问题，属于编辑器核心输入管线app/src/protyle内部的细节修正，本版本未改变触发语法本身，只改善了触发时机与粘贴合并逻辑。

数据视图（数据库）与搜索一致性

• 改進 Microsoft Excel 相容性；
• 資料庫過濾遵循搜尋的大小寫敏感設定；
• 改進資料庫資源欄位的圖片匯出尺寸；
• 匯出資料庫為 CSV 時包含關聯資源。

「資料庫過濾遵循搜尋的大小寫敏感設定」打通了搜索设置与 AV 过滤两个此前各自为政的开关。大小写敏感开关位于搜索设置页，见 app/src/config/tabs/searchTab.ts：

group.switch("search.caseSensitive", { ... });

从源码结构看，该配置项属于全局搜索配置search.caseSensitive，v3.5.4 之前数据视图的过滤条件不读取这一设置，两个入口的行为可能不一致；本版本让 AV 过滤条件在构造查询时同样遵循该开关，用户在全局设置里切换一次即可统一影响全文搜索与数据库过滤。

安全与隐私

v3.5.4 包含三项直接涉及安全的变更与一项同步加固：

• 任意檔案讀取漏洞（修复）；
• 預設不會執行伺服的 SVG 中的腳本以防止 XSS；
• 改進資料同步過程中的加密校驗；
• 提示使用者在非 SSD 硬碟上執行時可能的效能問題（性能提示，亦与本地数据环境评估相关）。

「預設不會執行伺服的 SVG 中的腳本以防止 XSS」针对的是 SiYuan 作为本地 Web 服务器托管工作区资源时的风险面：当用户请求工作区内的 SVG 资源时，若 SVG 内嵌<script>，直接在浏览器上下文执行可能被恶意构造的 SVG 利用。本版本默认禁用了这类脚本执行，属于「默认安全（secure by default）」策略。

「任意檔案讀取漏洞」的修复位于内核 HTTP 服务端：SiYuan 内核通过 Gin 路由暴露工作区文件接口，若路径拼接或前缀校验存在缺陷，攻击者可构造请求读取工作区外的系统文件。此类修复通常伴随路径规范化和工作区根前缀断言的强化，可在 kernel/server 与 kernel/api/file.go 的静态资源处理逻辑中追溯相关守卫代码。

「改進資料同步過程中的加密校驗」则对应加密工作区的同步链路：同步包在传输前后执行加密一致性校验，本版本改进了该校验的覆盖范围，降低同步过程中数据损坏或篡改被静默放过的概率。

平台、性能与运行时

• 插入資源的大小限制已從 8G 調整為 16G：单资源（图片、音视频等附件）插入上限翻倍，方便导入 4K 视频等大体积媒体；
• 改進網路伺服位址清單：优化设置页中「网络服务地址」列表的展示与生成逻辑，多网卡/多网段环境下地址列表更准确；
• 改進最近文件的處理：最近文件列表的更新与清理逻辑修正；
• 改進 macOS 初始化介面及暗黑模式支援：macOS 桌面端首次初始化界面的样式与系统深色模式联动；
• 改進瀏覽器與 PWA 中編輯器、閃卡和關係圖的全螢幕顯示：网页版与 PWA 下全屏 API 的兼容处理（浏览器 Fullscreen API 在不同标签页/iframe 上下文下行为差异的适配）；
• 區分被引用的定義塊是不存在還是未被索引：块引用报错时给出更精确的提示，便于排查「引用了尚未索引的块」与「块已被删除」两种情况；
• 減少桌面端應用的體積：打包产物瘦身；
• iOS 上無法進行水平滾動（修复）；
• 重新開啟已關閉的頁籤時不顯示其圖示（修复）；
• 在資料快照頁面執行某些操作後介面卡死（修复）；
• 在編輯器中使用滑鼠三擊未能選取全部文字（修复）；
• 標題等級批次轉換功能異常（修复）。

运行时层面，变更日志标注的重构项是「升級至 Electron v39.3.0」。需要说明的是，当前仓库主分支的 app/package.json 中 Electron 依赖已演进为更高版本（"electron": "42.6.1"），即 v3.5.4 发布时点的基线是 v39.3.0，后续版本继续滚动升级。桌面端打包脚本同样在 app/package.json 中可见，通过electron-builder配合多平台配置文件（electron-builder.yml、electron-builder-darwin-arm64.yml、electron-builder-linux-arm64.yml等）产出各平台安装包：

"dist": "cross-env ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ electron-builder --config electron-builder.yml --publish=never", "dist-arm64": "electron-builder --arm64 --config electron-builder-arm64.yml --publish=never", "dist-darwin-arm64": "electron-builder --arm64 --mac --config electron-builder-darwin-arm64.yml --publish=never"

「減少桌面端應用體積」与上述打包配置直接相关，常见的瘦身手段包括压缩内置资源、裁剪平台无关资产等。而「提示使用者在非 SSD 硬碟上執行時可能的效能問題」则是启动阶段的硬件探测：SiYuan 的索引与块存储依赖大量小文件随机读写，机械盘上性能差距明显，本版本在检测到非 SSD 环境时给出用户提示，帮助用户理解潜在的卡顿来源。

变更条目全量索引

为便于逐条检索，以下按变更日志原始分组完整列出 v3.5.4 的全部条目（原文中的外部 issue 链接已按规范省略）：

版本要点总结

1. 导出是主战场：内置 Pandoc 模板（pandoc-template.docx）+ 颜色过滤器（pandoc_color_filter.lua）+ 可自定义 Pandoc 参数的通用转换接口（kernel/api/pandoc.go），构成了本版本 .docx 导出体验改进的完整底座；.sy.zip多选导出与「包含子文件/关联文件」开关则扩展了打包导出的覆盖面。
2. 安全默认收紧：伺服 SVG 脚本默认不执行、任意文件读取漏洞修复、同步加密校验加固，三项变更都指向同一方向——本地自托管服务面的攻击面收缩。
3. 行为一致性：AV 过滤遵循搜索的大小写敏感设置，消除了两个入口间的配置割裂；块引用错误提示细分「不存在」与「未索引」，提升了排障精度。
4. 运行环境基线：发布时点桌面端升级至 Electron v39.3.0（当前仓库主分支已演进至 42.x），资源上限提升至 16G，并对非 SSD 环境给出性能提示。

适用前提说明：本文基于当前仓库主分支代码与 v3.5.4 变更日志 撰写；变更日志描述的是 v3.5.4 发布时点的行为，而仓库中的实现（如 Electron 版本、部分导出逻辑）可能已随后续版本演进，阅读源码时请以对应版本的 changelogs 为准。

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan