VSCode不内置离线文档模块化管理功能，需手动按技术栈和版本号分层建目录（如docs/python/3.12/），配合tasks.json配置打开任务，并用Live Server或Python本地服务器启动以规避file://协议限制。
VSCode 本身不提供“离线文档按模块分类保存”的内置功能，它不托管或生成官方 API 文档；所谓“离线文档”，实际指你本地保存的第三方文档（如 Python 官方 HTML 文档、TypeScript 手册、Vue.js 离线版等）或插件附带的说明文件。这类文档的组织方式完全由你控制，关键在于路径结构 + VSCode 的文件关联逻辑。
文档文件夹必须用语义化子目录隔离模块
直接把所有 HTML/PDF/MD 文件丢进一个 docs 文件夹会导致后期难定位、搜索慢、打开混乱。真实有效的做法是按技术栈分层建目录：
-
docs/python/3.12/：放 CPython 官方离线文档（含index.html） -
docs/typescript/5.5/：放 TypeScript Handbook 的静态导出版 -
docs/vue/3.4/：放 Vue 官网vuejs.org的离线镜像（需保留原始路径结构） -
docs/vscode/1.85/：放 VSCode 官方code.visualstudio.com的 PDF 或 HTML 打包版
注意：3.12、5.5 这类版本号必须显式出现在路径中——不同大版本文档结构差异极大（比如 Vue 2 和 Vue 3 的 API 分类完全不同），混在一起会误导跳转。
在 VSCode 中快速打开指定模块文档要靠自定义任务 + 快捷键
VSCode 不会自动索引你硬盘上的 HTML 文档，必须手动建立入口。最稳的方式是写一个 .vscode/tasks.json，为每个模块配一条打开命令：
{
"version": "2.0.0",
"tasks": [
{
"label": "Open Python Docs",
"type": "shell",
"command": "open docs/python/3.12/index.html",
"osx": { "command": "open docs/python/3.12/index.html" },
"windows": { "command": "start "" docs\python\3.12\index.html" },
"linux": { "command": "xdg-open docs/python/3.12/index.html" }
}
]
}
然后按 Ctrl+Shift+P → 输入 Tasks: Run Task → 选 Open Python Docs 即可秒开。别依赖“在资源管理器里双击”，那会脱离 VSCode 上下文，也无法绑定快捷键。
浏览器缓存和本地服务器才是离线文档真正可用的前提
很多离线文档（尤其是 Vue/React 官网镜像）依赖前端路由或 AJAX 加载侧边栏，直接双击 index.html 会白屏或报 net::ERR_FILE_NOT_FOUND。这不是路径错了，是浏览器安全策略阻止了 file:// 协议下的跨文件读取。
- 正确做法：用 VSCode 插件
Live Server右键index.html→Open with Live Server，它起一个本地http://127.0.0.1:5500服务，所有相对路径都能正常解析 - 更彻底的方案：用 Python 起服务（确保离线可用）：
python -m http.server 8000，然后访问http://localhost:8000/docs/python/3.12/ - 千万别用
file:///链接分享给同事——99% 会失败，尤其 Windows 上 IE 兼容模式默认禁用
真正容易被忽略的点是：文档的“模块”不是靠文件名识别的，而是靠目录层级 + 服务协议共同决定的。你把 vue/3.4/ 改成 vue/latest/，再用 Live Server 打开，它不会自动重定向到最新版——因为离线文档没有后端逻辑。版本必须硬编码在路径里，且所有内部链接（比如侧边栏跳转）都得是相对路径，否则一点击就 404。
