项目地址

在线体验：

https://ai-studyhub.cn

GitHub：

https://github.com/Earth-OL-Player/ai_learn_project

如果你正在学习 AI Agent、RAG、大模型应用开发，或者刚好想在 Vue 项目里做一个 Markdown 长文页面，可以参考这个实现。

一、先说实话：学习路线页面技术难度不高

最近开源了一个 Agent 学习平台。前几篇文章分别写了项目整体、AI 智能刷题和成长体系，这篇聊一个看起来没那么“AI”的模块：学习路线。

在线体验：

https://ai-studyhub.cn

GitHub：

https://github.com/Earth-OL-Player/ai_learn_project

学习路线这个页面，单看技术并不复杂。它没有调用大模型，也没有复杂的后端业务，甚至主要内容就是一份 Markdown。

但我还是把它单独拎出来写，是因为这个模块很容易被低估。

很多人学 AI 应用开发的时候，第一步不是写 Agent，也不是调 RAG，而是在各种资料之间来回跳：今天看到 LangChain，明天看到 LangGraph，后天又有人推荐 LlamaIndex，再刷到向量数据库、Function Calling、RAGFlow、模型微调。看着都重要，结果越学越乱。

我自己也绕过这个弯。

所以在这个项目里，我没有把学习资料随便堆在 README 里，而是做成了一个正式页面。它的作用很朴素：让第一次进来的用户知道先看什么、后看什么，哪些是主线，哪些暂时不用急。

二、这条学习路线放了哪些东西

当前资料页主要围绕 AI 应用开发，不是大模型训练，也不是底层推理优化。

主线大概是这样：

Python
  -> LangChain
  -> LangGraph
  -> RAG
  -> LlamaIndex
  -> 向量数据库
  -> Agent 和 RAG 项目实践

页面里现在整理了这些方向：

• Python
• LangChain
• LangGraph
• RAG 通识
• LlamaIndex
• 向量数据库
• Hello Agent
• RagFlow
• learn-claude-code
• 微调和推理加速相关误区

这里我刻意写了“误区”这一节。

不少 AI 应用开发教程会把微调、推理加速、CUDA Kernel、vLLM 这些内容一股脑塞进来。它们当然有价值，但对多数想做 AI 应用的开发者来说，优先级没那么靠前。

如果目标是先把 AI 能力接进业务系统，那更应该先搞清楚模型调用、上下文组织、工具调用、RAG 检索质量、结构化输出和工程接入。

这个判断不一定适合所有人，但至少适合我这个项目的定位。

三、为什么不用 Vue 组件硬写内容

学习路线本质上是内容，不是交互组件。

如果把大段资料直接写在 Vue 文件里，会有几个麻烦：

1. 内容维护和页面代码混在一起。
2. 链接、表格、引用、代码块都不如 Markdown 顺手。
3. 图片资源不好跟正文一起管理。
4. 后面改资料时，总感觉自己在改业务代码。

所以我最后选择用 Markdown 维护内容。

核心文件在这里：

ai-learn-web/src/content/learning-roadmap/AI应用开发学习路线和资料集.md

图片资源放在同级目录：

ai-learn-web/src/content/learning-roadmap/AI应用开发学习路线和资料集.assets/

这种组织方式比较接近写文档。以后我要补一个新章节，或者替换一张路线图，基本只需要动 Markdown 和图片，不用去翻组件模板。

四、页面代码怎么拆

学习路线页面主要涉及这几个文件：

ai-learn-web/src/pages/learning-roadmap/LearningRoadmapPage.vue
ai-learn-web/src/components/common/MarkdownToc.vue
ai-learn-web/src/utils/markdownToc.ts
ai-learn-web/src/utils/safeMarkdown.ts
ai-learn-web/src/styles/markdown.scss

页面结构很简单：

左侧：目录
右侧：Markdown 正文

在 LearningRoadmapPage.vue 里，Markdown 原文是通过 Vite 的 ?raw 引进来的：

import roadmapMarkdown from '../../content/learning-roadmap/AI应用开发学习路线和资料集.md?raw';

这样引入后，Markdown 文件会变成一个字符串。后面再交给 markdown-it 渲染成 HTML。

我比较喜欢这种方式，因为它没有额外引入文档系统，也没有把简单事情做重。这个项目还不是大型文档站，用 Vite 原生能力已经够了。

五、用 v-html 前先把 HTML 洗干净

这里有个容易踩坑的点：Markdown 渲染出来以后，最终还是要通过 v-html 放到页面上。

如果直接渲染，风险就来了。

比如 Markdown 里混入 script、iframe、表单、内联 style，页面可能会出现安全问题，也可能污染整站样式。即使目前内容都是自己写的，也不建议偷懒。项目后面一旦开放后台编辑、导入资料或多人维护，这个坑会变大。

所以我抽了一个 safeMarkdown.ts：

Markdown 原文
  -> markdown-it 渲染
  -> DOMPurify 清洗
  -> 放到页面上

里面做了几件事：

• 默认不允许原始 HTML。
• 只保留 Markdown 正文会用到的标签。
• 禁掉 script、iframe、form、style 这类标签。
• 移除内联 style。
• 给链接加上 target="_blank"。
• 给链接补 rel="noopener noreferrer"。

这些处理不花哨，但我觉得很必要。

很多项目早期会觉得“内容都是我自己写的，没事”。等功能越做越多，再回头补安全处理，改动反而更大。

六、长文没有目录真的很难读

学习路线不是短文，一屏肯定放不完。

如果只把 Markdown 渲染出来，用户需要一直滚动，也不知道自己读到哪一段。尤其是在手机上，体验会更明显。

所以我加了一个通用目录组件：

ai-learn-web/src/components/common/MarkdownToc.vue

目录生成逻辑放在：

ai-learn-web/src/utils/markdownToc.ts

当前只收集二级到四级标题：

## 二级标题
### 三级标题
#### 四级标题

一级标题一般是文章标题，没必要进目录。五级、六级标题进来后目录会太碎，看起来反而乱。

锚点 ID 也做了重复标题处理。

比如页面里有两个“学习资料”，生成锚点时第二个会自动带序号，避免点击目录时跳错位置。

这个细节不大，但长文里很常见。很多 Markdown 页面刚开始都没问题，内容一多，重复标题就出现了。

七、目录高亮和手机端折叠

目录除了能点击，还会跟随滚动高亮。

实现上用的是 IntersectionObserver。页面挂载后，监听正文里的 h2、h3、h4 标题。当某个标题进入视口附近，就把它设置成当前目录项。

这类交互没什么炫技成分，但对阅读长文很有帮助。用户滚动到 RAG 或向量数据库章节时，目录能跟着变，不需要自己判断位置。

手机端我做了默认折叠。

原因也简单：手机屏幕本来就小，如果一进页面先看到一长串目录，正文会被挤到后面。默认收起来，用户需要时再展开，会舒服一些。

八、Markdown 里的图片怎么处理

学习路线里有两张图：

AI应用开发学习路线.webp
向量数据库分类图.webp

它们放在 Markdown 同级的 assets 目录里。

页面里用 import.meta.glob 扫描资源目录，然后把 Markdown 中的相对路径转换成 Vite 可以访问的资源地址。

这样做主要是为了维护方便。

如果把图片全放到 public 目录，时间久了会很乱。现在图片跟着这篇资料走，哪天移动或删除这篇资料，相关图片也能一起处理。

图片渲染时还加了：

loading="lazy"
decoding="async"

长文页面里图片不一定都在首屏，懒加载可以少抢一点首次加载资源。

另外我给图片自动包了一层 figure，再根据图片 alt 生成图注，比如：

图1-AI应用开发学习路线
图2-向量数据库分类图

这不是必须功能，但放在学习资料页里会更像一篇正式文章。

九、学习路线不应该孤零零地存在

如果只是做一个学习路线页面，其实没太大意思。网上类似文章很多。

我更想做的是把它放进一个学习流程里：

看学习路线
  -> 按方向补基础
  -> 看热门面试题
  -> 用 AI 智能刷题练表达
  -> 根据评分结果回头查漏补缺

也就是说，学习路线解决“我先学什么”的问题；面试题库解决“这些知识会怎么问”的问题；AI 智能刷题解决“我能不能讲清楚”的问题；成长体系负责记录长期练习结果。

这也是我做这个项目时一直想保留的思路：不要只堆资料，要让用户能练、能复盘。

十、这套实现适合哪些场景

如果你的项目里也有大量长文内容，这套方式可以直接参考。

比较适合：

• 项目 Wiki
• 技术文档页
• 开源项目介绍页
• 内部培训资料
• 在线课程讲义
• 面试题解析页
• 产品更新日志

如果压缩成几句话，就是：

内容交给 Markdown
页面负责渲染和交互
目录从标题自动生成
图片跟着文档管理
HTML 输出统一清洗

不要一上来就搭复杂文档站。小项目先用轻一点的方案，后面内容规模真的上来了，再迁移也不迟。

十一、我踩完后的几个结论

这次做完学习路线页面，我的感受是：

1. 学习路线最难的不是页面，而是取舍。
2. Markdown 适合维护长文，但渲染到页面前一定要做安全处理。
3. 长文页面最好有目录，否则用户很容易失去位置感。
4. 图片资源跟着 Markdown 放，比散落在 public 目录里好维护。
5. 移动端目录要克制，默认折叠比默认展开更合适。
6. 学习资料如果能和刷题、题库、复盘连起来，价值会比单篇文章高很多。