站点说明
前言
此前，我尝试过多种知识管理工具，例如：飞书云文档、语雀和 Notion。这些平台在协作和使用便捷性方面确实表现出色，但在长期使用过程中也暴露出一些不足。
- 飞书云文档：更适合团队协作，能在多人编辑中展现高效的协同能力，但在长文档的编辑过程中偶尔会出现页面卡顿的问题。
- 语雀：功能完善、结构清晰，适合系统化管理知识，但批量导出不便、数据迁移不够友好。
- Notion：自定义灵活、模板丰富，能够构建多样化的个人知识体系，也支持导出内容。然而，复杂数据结构（如数据库、关联块等）导出后往往难以保持完整一致，且国内访问速度不稳定，存在访问受限与迁移不确定性。
综合来看，这些工具虽在体验上各有优势，但都难以满足我对长期可控性和完全自定义的要求。因此，我逐渐意识到：要构建一个真正稳定高效、能长久运转的知识库，就必须拥有一个完全属于自己的平台。经过对多种框架的对比，我最终选择了
Astro作为基础框架。
框架
本站基于 Astro 构建，以实现高性能的静态站点。Astro 非常适合内容型网站，既保证极速加载，又能灵活引入交互功能。
- 极致性能：以内容为核心，默认输出静态 HTML，页面加载速度快。
- 按需加载：仅在需要时加载
React、Vue、Svelte等组件，无需全量打包，优化资源消耗。- MDX 支持：在 Markdown 中无缝嵌入 Astro 组件 和 UI 框架组件，使内容展示更灵活、交互性更强。
- SEO 友好：支持服务端渲染（SSR）与静态生成（SSG），并可通过
@astrojs/sitemap、astro-og-canvas等工具自动生成站点地图与社交卡片。- 丰富的模板与主题：官方及社区提供大量的模板和主题，开箱即用，助力快速搭建个人博客、文档站点或作品集。
UI
Tailwind CSS 是高效的原子化样式框架，配合
@tailwindcss/typography插件，可显著优化 Markdown 的排版和渲染效果，提升文章阅读体验。Preline 提供了丰富的基础 UI 组件，方便快速构建网站的通用界面元素，减少重复开发，提高开发效率。
Astro Icon 是专为 Astro 项目设计的图标组件库，支持按需加载矢量图标。它利用 Astro 的构建时编译特性，把图标在构建阶段直接编译为内联 SVG。与传统图标库相比，它无需额外打包或依赖，从而减少了项目的体积，提高了加载速度。
动画
GSAP：实现基础交互动画，提供强大的时间轴控制和缓动效果。
Lenis：替代浏览器默认滚动，实现平滑滚动体验。在页面动画复杂时可能出现掉帧，可考虑使用 GSAP 的
ScrollSmoother插件替代。主题切换动画：为明暗主题切换提供自然流畅的过渡效果。
Rough Notation：提供手绘风格标注与强调效果，用于突出文本或页面元素。
评论
一开始，我选择使用
Disqus作为评论系统。Disqus是目前最流行的第三方评论托管平台之一，集成非常简单，只需嵌入一段代码即可快速启用评论功能，无需自己搭建服务器。优点是使用方便，支持邮件通知功能，能够及时获知评论动态；缺点是免费版本会在评论区显示广告，并且在国内网络环境下访问可能受限。
后来，我尝试使用
Giscus作为兜底方案。Giscus基于GitHub Issues提供评论托管，不依赖第三方服务器，评论数据直接存储在 GitHub 仓库中。优点是没有广告、支持主题自适应；缺点是依赖 GitHub 登录，国内用户可能存在访问速度不稳定（相对Disqus来说，较稳定，Disqus由于网络限制，完全无法使用）或登录门槛较高的问题，使用体验不如预期。
最终，我选择直接部署
Waline来作为评论系统。Waline是一款轻量、开源的自建评论系统，数据可控，可自定义主题和功能。优点是访问速度快、可完全掌控数据、支持多种通知方式；缺点是需要自己部署服务器或使用云端服务，初始配置相对复杂。
注意评论数据存储在 LeanCloud 的免费版数据库中，由于每天的 API 请求次数有限，偶尔可能会出现评论区无法加载的情况，这是因为请求量超出了限额。
此外，文章阅读量统计功能由 Waline 提供，因未对短期内的重复访问进行去重处理，数据可能存在一定偏差，仅供参考。
为了进一步提升评论通知体验，我还配合使用了
Bark。Bark是一款基于iOS的消息通知工具，可以与Waline集成，实现当有人发表评论时，将评论通知即时推送到手机上。优点是推送及时、使用便捷、不依赖邮件系统；缺点是需要使用 iOS 设备，并且需要先安装 Bark App 并配置推送密钥。
归档
与常见的基于时间轴的归档不同，本站使用 FullCalendar 来实现文章归档功能，用户可以直观地查看每日文章发布情况。
时间轴通常以列表形式按年月排列文章，用户需要逐页翻阅才能查看历史内容。而 FullCalendar 提供多种视图模式（如：月视图、周视图、多月视图…，这里只使用了两种视图），并可通过
@fullcalendar/react在 React 中快速集成，实现交互式日历展示。用户不仅能够一目了然地看到每天的文章发布情况，还可以点击日期查看每日发布的具体文章，大大提升了归档的可视化和交互体验。
搜索
最初，我尝试使用 DocSearch 来实现搜索功能。它集成简单，只需引入组件即可，而且性能优秀，但在自定义界面和交互上存在一定局限。
后来，我改用 Fuse.js 来实现搜索逻辑，并完全自定义 UI，从而获得更灵活、可控的搜索体验。考虑到文章数量可能会持续增加，为了获得更高效、精准的搜索体验，我最终选择使用 Algolia。不同于直接使用
DocSearch提供的 React 组件，我通过更灵活的 REST API 进行集成。同时，借助 Algolia 平台提供的 Crawler，可以自动、及时地抓取并更新网站文档数据，从而保证搜索结果的实时性与准确性。为了保证搜索结果的准确，需要及时更新爬虫数据。
链接预览
为了实现类似
Notion的链接预览功能，本站引入 link-preview-js 来获取链接的元数据（如：标题、描述、封面图等），并在此基础上自定义预览卡片，将普通链接转换为直观的卡片展示，从而提升文章的可读性和交互体验。为了优化性能，减少重复请求，本站采用了多层缓存策略：
Cloudflare D1 SQL 数据库：对元数据进行持久化，可直接在数据库中修改失效的 meta 信息，再重新请求更新；
Cloudflare KV 数据库：存储热点数据，实现快速读取；
浏览器 IndexedDB：缓存已访问的元数据，减少网络请求，加快用户访问速度。
注意由于链接的
icon图标和文章插图采用了懒加载，页面在滚动过程中可能会出现高度变化，因此通过目录跳转时，定位位置可能不完全准确。虽然已对这一问题进行了优化：在滚动过程中，当图片加载导致页面高度变化时，会自动校正滚动位置，以确保最终定位尽量准确。但在少数情况下（尤其是页面中图片较多时），如果跳转完成后图片才开始加载，页面可能不会再次滚动以适应新的高度。对此，也可以在 Markdown 文件中为图片设置宽高，以完全解决该问题。
另外，在通过目录点击跳转的过程中，已经禁用了手动滚动，以免对滚动位置带来干扰。
代码执行
为了实现在线代码执行功能，本站最初使用了 piston-client。Piston 是一款轻量级的开源代码运行引擎，支持多种主流编程语言，能够在隔离环境中安全地编译并运行用户提交的代码，使读者在阅读文章或教程时可以直接在页面中运行代码并查看结果。
由于
Piston对 Java 的中文输入支持不佳，所以对于含有中文的 Java 源代码，我使用了 Judge0 来运行。需要注意的是，Judge0对每日的提交次数有额度限制，并且对于 Java 代码，public class必须命名为Main。此外，为了提升交互体验，我进一步集成了 codemirror ，使代码块可直接编辑，读者不仅可以在线运行示例代码，还能修改和测试自己的代码，从而更方便地进行学习。
建议由于网络环境和公共接口的资源分配有限，
Piston和Judge0可能出现运行超时的情况，因此建议使用自部署的代码执行平台。
网站内容
本站内容主要源于我过往在各类知识库平台积累的学习笔记，部分原始笔记因故遗失。有的文章是在参考学习视频及相关资料的基础上，结合个人理解整理而成，旨在便于后续复习、修改与查阅。
文中所使用的插图多来源于网络，出于对视觉风格统一的考虑以及个人偏好，未来计划采用 Excalidraw 来重绘某些流程图。
