VSCode 原生不支持 PDF 渲染，必须安装且仅认准 tomoki1207 发布的 PDF Viewer 插件；安装后需全量重启 VSCode 才能注册右键菜单与命令，路径含中文或空格、文件超 50MB 或扫描版 PDF 均会导致预览失败。
VSCode 原生不支持 PDF 渲染，所谓“直接阅读”完全依赖插件；目前唯一稳定、持续维护、能真正内联预览的只有 PDF Viewer（作者 tomoki1207），其他名字近似的插件要么停更、要么已下架、要么卡死大文件。
怎么装对插件：认准发布者和名字
在 VSCode 扩展市场搜索时，必须输入 PDF Viewer（注意大小写和空格），且只认发布者为 tomoki1207 的那一项——它不是 vscode-pdf，也不是 PDF（by chenxsan），更不是旧名 vscode-pdfviewer（该仓库已归档）。后者在 2025 年后已无法通过市场安装，强行手动安装会触发签名警告或加载失败。
- 错误现象：
Open Preview右键菜单不出现、双击 PDF 报错command 'pdfview.openPreview' not found - 根本原因：装了非官方分支，或插件未启用，或 VSCode 没重启
- 验证方式：打开
Extensions面板，搜索PDF Viewer，看右下角是否显示Enabled，发布者字段是否为tomoki1207
为什么必须重启 VSCode 才生效
VSCode 的插件注册机制要求 UI 类扩展（尤其是添加右键菜单、注册新命令的）在启动阶段完成初始化。PDF Viewer 注入了 pdfview.openPreview 命令并监听 .pdf 文件类型，这些动作只在启动时扫描一次。不重启，VSCode 仍按旧配置运行，右键菜单不会刷新，Ctrl+P 里也搜不到相关命令。
- 常见误操作：点完“安装”就立刻双击 PDF，以为自动生效
- 实际行为：文件用系统默认程序打开，或提示“无法打开此文件”
- 省事做法：安装后直接按
Ctrl+Shift+P→ 输入Developer: Restart Extension Host，但不如全量重启稳妥，尤其 Windows 上容易残留旧进程
打开后渲染异常的几个硬性限制
PDF Viewer 基于 PDF.js 渲染，这意味着它继承了浏览器级 PDF 解析能力的全部边界：不能处理扫描版 OCR 文本层缺失的 PDF，不支持 DRM 加密文档，对含复杂表单/JavaScript 的交互式 PDF 仅做静态快照。
- 典型症状：页面空白、卡在 loading、文字乱码、缩放后模糊、翻页卡顿超过 3 秒
- 路径陷阱：项目路径含中文或空格（如
D:\我的文档\tech\api.pdf）会导致 PDF.js 加载失败，报错Failed to load PDF file - 文件大小红线：超过 50MB 的 PDF 极易触发内存溢出，表现为预览标签页白屏 + CPU 占用飙高；建议先用
qpdf --stream-data=none压缩再导入 - 替代方案：若必须查扫描件，用系统自带预览器；若需注释，别硬扛，直接切到 SumatraPDF 或 Edge
预览体验优化：几个关键设置项
默认配置适合快速查看，但技术手册常需精准定位。在 VSCode 设置中搜索 pdfviewer，可调整以下几项：
-
pdfviewer.defaultZoom：设为page-width比auto更可靠，避免首次加载时文字过小 -
pdfviewer.enableTextSelection：开启后支持复制文本（但扫描件无效） -
pdfviewer.enableBookmarks：技术文档若有书签目录，这个开关决定是否显示侧边栏导航 -
pdfviewer.useWorker：保持启用，否则大文件解析会阻塞编辑器主线程
这些设置改完无需重启，但已打开的 PDF 标签页需手动刷新（右键 → Reload Preview）才生效。
最常被忽略的是路径问题——哪怕插件装对、重启到位、设置调优，只要 PDF 文件路径里有中文或空格，预览就会静默失败。这不是 bug，是 PDF.js 在 Electron 环境下的安全策略限制，绕不开。
