去年有段时间我几乎把市面上所有笔记软件都折腾了一遍。从老牌的 Evernote 到后来红极一时的各类本地优先笔记应用每个都用了几个月但始终觉得哪里不对劲。要么是数据格式锁死换工具就是一场灾难要么是同步逻辑黑盒本地文件到底存了啥、什么时候上传的完全凭它说了算最要命的是版本管理手滑删了一大段内容找回来全靠运气。后来我索性把整个笔记体系推倒重来用最土的方案组合Markdown 写内容NAS 管存储Git 做版本和历史追溯。这套组合稳定跑了将近一年再也没换过笔记软件。中间当然踩了不少坑有些坑查资料都查不到答案只能自己翻日志、看源码才搞明白。这篇文章就按“架构设计 - 工具选型 - 实操细节 - 问题排查”的顺序把我这套折腾经验完整的捋一遍。1. 整体方案设计为什么是 Markdown NAS Git 三件套先说结论把笔记拆成“内容格式、存储位置、版本管理”三个互相独立的维度各管各的比任何全家桶方案都稳得多。想明白这个逻辑之后你再看那些一体化笔记软件思路会清晰很多。1.1 三者分工与选型思路Markdown 负责内容表达纯文本、有统一语法规范、不依赖任何特定软件才能打开。哪怕十年后所有笔记软件都倒闭了你用系统自带的记事本都能把内容完整读出来这是我对“数据主权”的最低要求。NAS 负责文件存储和备份所有笔记文件实打实地落在一块你自己控制的硬盘上不用担心某个云端服务突然停止运营也不用担心免费容量上限。配合硬盘 RAID 或者定时快照数据安全性能做到比大多数云盘更可靠。Git 负责变更追踪和多端同步每个历史版本都完整保存在 Git 仓库里写错了能回滚删多了能找回还能看到每一次修改的差异对比。远程仓库往 NAS 上一放家里电脑、公司电脑、笔记本随时同步永远不需要拿 U 盘来回拷贝。这三者的关系有点像“毛坯房 物业 监控”Markdown 是毛坯房本身什么风格都能装修NAS 是物业负责帮你保管钥匙、定期检查水电Git 是楼道里的监控摄像头每笔改动都记录在案出了事能回放现场。1.2 这套方案的核心优势用 Markdown 的这几年我最大的体会是“不绑架”。对比一下传统笔记软件数据基本都存在私有格式里你只是拥有“使用权”。而 Markdown 文件就是普普通通的纯文本扩展名是 .md任何设备、任何系统都能直接打开。Git 带来的版本回溯能力更是传统笔记软件比不了的。传统笔记软件大多只能恢复到特定时间点的备份而 Git 可以精确到某一次提交甚至能对比两个历史版本之间像素级的差异。写长文的时候我经常上午写一版思路、下午推翻重写有了 Git两个版本我都能留着随时切回去对照。有人可能会问直接用带同步功能的笔记软件不就能自动备份历史版本吗但那是“一个产品做三件事”。我这边是三个领域里各自最专业的工具组合Markdown 的语法通用性、NAS 的存储可靠性、Git 的版本管理能力都是各领域里久经考验的成熟方案。整合度可能不如全家桶但任何一环出了问题替换成本都极低。1.3 适合什么场景、什么人这套方案最合适的是笔记量较大、对数据有长期积累计划、愿意花一点时间配置环境的人。比如写技术博客的、做知识管理的、搞学术研究的、写小说或长篇连载的。如果你只是想随手记个购物清单、临时想法那确实没必要搭这么一套环境手机自带的备忘录就够了。但如果你打算在某个领域持续积累三五年或者手里攒着几年的写作素材、项目文档、工作日志那这套方案带来的长期价值会远远超过开始那半天配置时间。就像我常对朋友说的笔记软件是租房子这套方案是买地皮自己盖前期费点劲但房子永远是你的。2. 工具选型解析NAS 系统、Markdown 编辑器、Git 服务端怎么选三件套确定之后接下来就是具体的工具选型。这一部分我踩的坑最多所以会把每个选项的对比、取舍逻辑都写清楚你看完可以直接照抄。2.1 NAS 硬件与系统怎么低成本的跑起来先说 NAS 硬件。很多人一听 NAS 就觉得要花几千块买成品其实完全不必。我一开始用的就是一台退役的旧笔记本电脑拆掉屏幕装了个轻量 NAS 系统功耗才十几瓦当家庭存储服务器跑了半年多非常稳定。如果你手头没有旧电脑也可以看看二手市场那些小主机几百块就能拿下。关键是 CPU 不用太强内存建议 4GB 以上硬盘一定要选好。笔记数据本身占不了多少空间但你会慢慢往里放书籍 PDF、照片、视频素材所以硬盘容量按未来三年规划比较稳妥。系统方面商用成品机一般自带系统体验省心但定制性差点。喜欢折腾的可以看看开源方案像 TrueNAS、OpenMediaVault还有国内社区比较活跃的 fnOS。我个人的建议是新手先用自带系统或者对新手友好的方案跑通全流程等基础架构稳定了再考虑要不要换。2.2 Markdown 编辑器的三种选择方向Markdown 编辑器是整个链条里你每天直接面对的工具选顺手的很重要。根据使用习惯大致分三类极致简洁型打开就是一个输入框界面干净专注于写。代表是 Typora 这一类所见即所得工具左边写右边出效果对新手尤其友好不用记太多语法。但注意它在新版本后开始收费了不过买断价格不高重度使用还是很值的。插件扩展型以 VS Code 和 Obsidian 为代表。VS Code 本身是代码编辑器装个 Markdown 插件后写笔记很强还能顺便处理代码片段、画流程图。Obsidian 的双链笔记功能在知识管理场景下非常能打而且它直接管理本地 Markdown 文件和我们的方案完全契合。极客终端型直接在终端里用 Vim 或 Emacs 写配合各种插件实现高亮和预览。这个门槛偏高但一旦习惯了效率非常夸张适合本身就在终端里工作的人。我自己的选择是“双编辑器策略”平时用 Obsidian 做主力看中它的双链和插件生态需要快速记录或打开别人发的 .md 文件时就用 Typora。两个编辑器读的都是纯文本 Markdown完全无缝切换不存在兼容问题。2.3 Git 服务端用 Gitea 还是 Gogs还是直接用系统自带笔记要跨设备同步最好有个中心仓库NAS 上的 Git 服务端承担这个角色。选型上有老牌的 Gitea轻量且功能完整几秒钟就能启动非常适合个人和小团队用。Gogs 跟 Gitea 同源但更新节奏慢一些功能上略保守。如果你不想装额外应用还有更轻的办法在 NAS 上开一个 SSH 服务然后用 Git 自带的 SSH 协议访问仓库。相当于直接把 NAS 当成一台 Git 服务器不用装 Web 界面仓库管理通过命令行操作干净利落。缺点是每次管理仓库要走命令行没有网页图形界面那么直观。我的建议是如果你跟我一样偶尔需要在手机或者浏览器上翻看历史提交装一个 Gitea 最省心。如果纯命令行操作完全没问题SSH 方式少装一个应用更简洁。2.4 一个建议不要在 NAS 上直接改笔记文件这条经验是用代价换来的。最初我图省事直接在 NAS 的共享文件夹里用编辑器写笔记结果遇到两个问题一是通过 SMB 协议访问时一旦网络有波动编辑器可能会把未保存的修改写到临时文件里有时候会莫名冒出一些 .tmp 冲突文件二是有些编辑器对网络驱动器支持不好实时保存会有延迟。后来我把工作流改成所有笔记文件始终在本地磁盘上编辑Git 仓库在本地NAS 上只放远程仓库的镜像。写完一批内容执行一下 push改动就同步到 NAS 了。本地仓库和远程仓库分离本地负责高频读写NAS 负责存储备份与多端分发两边各干各的互不拖累。3. 核心配置实录从零搭好整套笔记环境理论说了一大堆接下来就是实操环节了。我把整套环境从零搭建的关键步骤、配置文件都列出来每一步都标注了容易出错的点。3.1 本地 Git 仓库初始化和全局配置本地环境以 macOS 为例Windows 的差异我会在括号里标注。首先要确保 Git 已安装安装后第一件事是设置身份信息这决定了提交记录里显示的作者名字git config --global user.name your-name git config --global user.email your-emailexample.com注意邮箱不一定非得真实邮箱但建议用你能长期记住的因为提交历史里的邮箱在后期排查问题时能帮你区分是哪台机器、哪个身份提交的。接着在笔记目录里初始化仓库cd ~/Documents/notes git init git add . git commit -m init: 建立笔记仓库如果笔记目录里已经有大量文件第一次 add 会比较慢这是正常的。初始化的这个提交最好保持干净不要混入临时文件。Windows 用户一定注意换行符问题。Git 默认会在提交时把 CRLF 转成 LF检出时再转回来但这个自动转换在多人协作或跨平台同步时经常惹麻烦。我的建议是加一个全局配置禁用自动转换git config --global core.autocrlf false这样所有文件都按原始字节保存不折腾换行符。代价是如果用老式 Windows 记事本打开 LF 换行的文件可能出现一行全挤在一起的情况但现代编辑器基本都兼容 LF这个代价完全可接受。3.2 SSH 免密登录配置把每次 push 的输密码环节彻底去掉Git 仓库同步用 HTTPS 协议每次都要输账号密码非常影响使用节奏。SSH 免密是必须配置的。整个流程分三步第一步本地生成密钥对ssh-keygen -t ed25519 -C notes-sync-key一路回车即可默认生成在~/.ssh/目录下。现代系统都支持 ed25519 算法比传统的 RSA 更安全、性能也更好。第二步把公钥添加到 NAS 或 Gitea 的 SSH Keys 设置里。以 Gitea 为例在网页后台的用户设置中找到“SSH / GPG Keys”把~/.ssh/id_ed25519.pub文件的内容粘贴进去。第三步测试联通ssh -T git192.168.1.100如果看到欢迎信息说明免密已生效。此时把远程仓库地址改成 SSH 格式git remote set-url origin git192.168.1.100:username/notes.git这步最坑的是权限配置。SSH 要求.ssh目录权限必须是 700公钥文件 644私钥文件 600权限太宽松会直接拒绝连接、报Bad owner or permissions。如果是 Windows 环境密钥文件复制到用户目录后也检查一下属性别继承到 Everyone 的读写权限。我这套环境能稳定跑大半年跟当时把权限一次配对了有很大关系。3.3 仓库路径规划与图片资源处理一个被很多人忽视的问题图片资源怎么处理。笔记里插图跑不了直接在 Markdown 里引用图片路径一旦放错换设备就显示一大堆裂图。我的方案是所有图片统一放进笔记仓库下的assets/目录按日期分子目录。引用时用相对路径这样整个仓库里文字和图片是作为一个整体保存的克隆到任何设备上相对路径都不会失效。你不需要配置什么图床也不需要担心第三方图床哪天挂了。代价是笔记仓库的体积会慢慢变大但对以文字为主的笔记来说一年下来也就几百 MB完全在 Git 可接受范围内。有两点要注意不要在 Markdown 里用绝对路径C:\Users\...\assets\xx.png或/Users/yourname/.../assets/xx.png换设备后百分之百裂图。大视频、大压缩包之类的文件不要放进 Git 仓库。Git 对二进制大文件支持很差会让仓库体积爆涨、克隆变慢。这类文件放到 NAS 的普通文件夹里笔记里引用相对路径即可。3.4 数学公式与特殊语法在不同平台间的兼容问题如果你经常写带数学公式的笔记Markdown 在这块的“标准不统一”会让你很头疼。最常见的坑是Typora 里显示正常的公式推到 GitHub 上却渲染不出来或者反过来。这背后是渲染引擎不同导致的。主流的 Markdown 渲染器有三种默认的普通模式、扩展了 LaTeX 数学公式的模式、以及加了脚注/目录等额外能力的模式。写作时尽量兼容最通用的语法尤其注意行内公式用单个$包裹如$x^2$块级公式用双$$包裹并单独成行。有的渲染器要求公式前后必须有空行否则识别成普通文本所以写完公式记得上下加空行。如果公式复杂比如多行联立方程需要用到\begin{cases}这类 LaTeX 环境。这种语法在不同渲染器里兼容性最差我的经验是写完公式后在两个不同平台上各预览一遍确认都正常再提交。表格也有类似的兼容问题。标准 Markdown 表格语法还算统一但有时你需要复杂的合并单元格、单元格内换行这就超过标准语法范围了。我的建议是复杂表格用 HTML 写在 Markdown 里table trtd styletext-align:center单元格1/tdtd单元格2/td/tr /tableHTML 表格在任何渲染器里都能识别不受 Markdown 方言差异影响。唯一要注意的是代码块里不要放 HTML 表格会被当纯文本转义。3.5 多设备自动同步定时 push 与拉取多端同步的原理很简单每台设备都有一个本地 Git 仓库改完内容后 push 到 NAS 远程仓库另一台设备 pull 下来。但“手动执行”这个动作很容易被遗忘所以值得做一点自动化。macOS/Linux 建议配一条 crontab# 每 30 分钟自动提交并推送一次笔记变更 */30 * * * * cd ~/Documents/notes git add -A git commit -m auto sync $(date) || true */30 * * * * cd ~/Documents/notes git push origin main || trueWindows 建议用计划任务配一个批处理脚本逻辑和上面一样。|| true的意思是如果没有变更导致 commit 失败直接忽略不影响下一次执行。这套自动同步方案我跑了很长时间非常省心。偶尔会遇到两地同时编辑导致冲突的情况但 NAS 是中心仓库谁先 push 谁生效另一个人 pull 时会看到冲突提示手工解决一下就行。日常记笔记这个频率的冲突极少出现真出现了也在可接受范围内。4. 常见问题与排查技巧实录这套系统跑了快一年遇到过各种各样的问题。我把真正高频、又多查资料都难找到答案的几个典型问题列出来附带排查思路和最终方案。4.1 SSH 认证失败的原因排查先给排查步骤状态码告诉你方向日志告诉你答案。用ssh -v打印详细调试信息ssh -vT git192.168.1.100看输出的最后几行常见错误Permission denied (publickey)公钥没配好或私钥没找到。检查 NAS/Gitea 后台的公钥内容和本地私钥是否对应。Connection refusedSSH 服务没启动或端口不对。ping 一下 NAS 确认网络通不通再确认 SSH 服务状态。Bad owner or permissions前面提过的权限问题把.ssh目录改回 700私钥改回 600。还有一个很多人忽略的点NAS 重启后 IP 地址可能变了。如果你用的是 DHCP 分配地址建议在路由器上给 NAS 设置 DHCP 静态绑定让它每次都拿固定 IP。否则某天 NAS 重启后拿了个新 IPGit 同步直接失败排查半天发现是地址变了非常浪费时间。4.2 Markdown 文件打不开或乱码大多数“打不开”其实是操作系统不知道用什么程序打开 .md 文件。解决方案很简单装个 Typora 或 Obsidian文件关联会自动建立。乱码就要区分情况了。最常见的是编码问题UTF-8 编码的文件被老版本 Windows 记事本以 GBK 打开中文显示成乱码。解决办法是换现代编辑器或者统一把文件保存为 UTF-8 无 BOM 格式。我用 VS Code 批量调整过一次历史文件的编码操作路径是打开文件后右下角点击当前编码选择“通过编码重新打开”选 UTF-8。还有一种是全角/半角符号混淆。中文输入法默认输出全角符号如果你的 Markdown 文件里出现全角冒号而不是半角:某些解析器会把整个块识别成错误格式。写作时尽量在英文状态下输入 Markdown 标点语法标记和中文内容之间可以留一个空格。4.3 .gitignore 过滤规则不生效想忽略某些文件在.gitignore里写了规则但完全不生效这种情况多半是规则本身写错了。比如你想忽略所有.DS_Store文件写了.DS_Store看起来没问题但如果文件已经被 Git 跟踪了.gitignore是不会对这个文件生效的。先取消跟踪git rm --cached .DS_Store.gitignore的匹配逻辑有几点容易踩/assets只匹配根目录下的 assetsassets/匹配所有目录下的 assets。*.log忽略所有 .log 文件但!important.log可以重新包含它注意父目录不能被忽略。规则写完后可以用git check-ignore -v 文件名验证到底哪条规则生效了非常实用。4.4 网页内容转 Markdown 的几个工具选择日常写笔记经常需要把网页内容保存成 Markdown这里推荐几个我用得顺手的方案浏览器扩展部分浏览器可以一键提取网页正文生成 Markdown方便快捷适合临时保存文章。命令行工具系统里备一个 Web 转 Markdown 的利器用法类似web-to-md URL -o output.md它的优势是能批量处理而且对代码块、图片的还原度比浏览器扩展更好。对复杂页面很多网页正文不是直接嵌在 HTML 里的而是通过 JS 动态加载这类页面需要先渲染完再抓取。我的经验是先在浏览器里把页面完整打开然后另存为 HTML再用工具做离线转换成功率会高很多。注意做这些转换时留意一下内容的版权授权个人学习笔记随手保存没问题但公开发布前看看来源网站的条款这是基本的网络礼仪。4.5 Markdown 表格复制到 Excel 显示错位做月度总结经常要把 Markdown 表格导成 Excel最省事的方法是直接用支持表格复制的编辑器Typora 里选中表格后可以直接粘贴到 Excel格式基本不丢。如果你手里的 Markdown 表格语法不规范比如某一行缺了分隔符或者单元格内容里带了竖线符号|都会导致解析错乱。检查一下这几处表头与内容之间的分隔行必须有三个以上短横线像|---|---|。单元格内容里如果确实需要竖线要用\|转义。每行的列数必须一致缺失列会导致后面的内容被挤到下一行。实在搞不定时我还有个终极大法转成 HTML 再进 Excel。Markdown 编辑器里导出 HTML用浏览器打开复制表格粘贴进 Excel兼容性极高。5. 这套方案还能怎么扩展核心系统搭建稳定之后后续的想象空间其实很大。这节不算总结纯粹是我自己折腾过程中的一些延展思路你按需参考。笔记系统跑顺以后我陆续把家里的其他文档管理也并了进来。比如合同扫描件、设备说明书、旅行行程单这些文件数量不多但很杂单独管理容易丢。我把它们统一放在 NAS 的归档目录下按年份和类别分文件夹并适当用 Git 做版本管理。文字类内容没问题但注意扫描 PDF 这类大文件还是会撑大 Git 仓库量大的话不要硬塞进仓库直接用 NAS 存储加定期快照就好。另外 Markdown 和各类自动化工具的结合也很有意思。很多自动化流程工具都能直接输出 Markdown 文件再配合定时任务可以把每日的监控数据、天气信息、新闻摘要自动收集并生成一份当日简报放到笔记目录里。早起打开笔记看今天的自动整理内容这种体验比打开各种 App 逐个刷新舒服太多了。我还搭建过一个简单的静态博客笔记仓库里的文章筛选后提交到博客仓库用 GitHub Actions 或 NAS 上的定时脚本自动构建部署。写笔记和发博客同一套文件不需要额外维护两套内容省掉了大量重复劳动。这些扩展都是基于三件套架构自然长出来的。核心思路永远一样内容永远是纯文本 Markdown存储永远在自己可控的位置变更永远可追溯。把这三个不变点抓住工具再怎么换、工作流再怎么调底层数据都不会乱。最后再分享一个个人建议这套系统刚搭好的时候也有一段时间嫌操作麻烦差点放弃。后来我把自动化做好、日常习惯固定下来之后就不觉得有什么负担了。先坚持一个月当这套流程成为肌肉记忆的时候你大概也会跟我一样,再也回不去那些数据困在某个 App 里的笔记软件了。