说实话，我一开始没想过要在 VS Code 里看视频。直到有一次线上演示，我一边给同事讲解代码逻辑，一边想播放一段操作录屏，结果在 VS Code 里双击视频文件，系统直接弹出了默认播放器，窗口一切换，演示节奏全乱了。
后来我花了一点时间研究，发现 VS Code 播放视频这件事，本质上只需要三步：装一个合适的扩展、把视频文件关联到编辑器、再顺手调一下播放设置。整个过程不像你想象中那么玄乎，但里面有些坑确实值得单独拿出来说。这篇文章就围绕这三步展开，顺便把我自己踩过的坑、排查思路都整理出来，给想在 VS Code 里直接看视频、边看边写代码的朋友一份完整参考。
1. 为什么 VS Code 默认不能播视频：编辑器的边界和扩展的原理
1.1 Electron 明明能播，但 VS Code 故意不放开
要搞懂 VS Code 播放视频这件事，得先明白一个常识：VS Code 是基于 Electron 开发的，Electron 底层是 Chromium 内核，Chromium 本身就是个浏览器，HTML5 的 video 标签天然支持 MP4、WebM 这些格式的播放。所以理论上 VS Code 完全可以内嵌播放器，但它默认就是不让你双击视频直接看。
这不是技术做不到，而是产品定位问题。VS Code 的核心场景是“编辑代码”，不是“播放媒体”。如果每个文件都默认走视频渲染，编辑器会变得很重，内存和 CPU 占用都会飙升，文件一多还会影响代码补全、git 操作这些核心体验。所以 VS Code 默认只处理文本、图片、PDF 等轻量预览，视频文件一律丢给系统默认程序。
我最初也试过直接把视频拖进 VS Code，结果它只是把视频当成二进制文件打开，屏幕上全是乱码，根本没有任何播放能力。这个阶段不用怀疑自己操作有问题，就是编辑器没有开放媒体解码器的通道。
1.2 扩展是怎么把播放能力“塞”进 VS Code 的
视频播放扩展之所以能做到，靠的是 VS Code 提供的两个核心扩展点：Custom Editor（自定义编辑器）和Webview（内嵌网页视图）。
Custom Editor 允许扩展注册一种新的编辑器类型，比如把*.mp4文件关联到一个自定义预览界面；Webview 则允许扩展在编辑器内部打开一个完整的 HTML 页面，这个页面里可以使用<video>标签、JavaScript 播放器、甚至字幕插件。
我可以用一个生活化的类比来解释：VS Code 是一个功能房，默认只摆了办公桌和台灯；视频播放扩展就是你在房间里开了一扇窗户，窗户本身自带播放能力，但窗户的位置、大小、开关方式由扩展说了算。所有视频的渲染实际上发生在 Webview 窗口里，VS Code 只负责把这个窗口嵌到编辑器布局中。
理解这一点很重要，因为后面所有排错、性能优化、功能扩展，都离不开这三个关键词：Custom Editor、Webview、video 标签。
1.3 视频扩展的三类实现方式
市面上能用的视频扩展，实现思路大致分三类：
- 基于 Custom Editor 的播放器：注册为视频文件的默认编辑器，双击文件直接在编辑器标签页里打开，体验最接近“VS Code 原生功能”。
- 基于 Webview 的独立播放面板：通过命令面板唤起一个独立面板来播放视频，适合边看视频边写代码，但不占用文件标签页。
- 基于 Markdown 预览的嵌入式播放：在 Markdown 文档里用 HTML 语法嵌入视频，写技术教程、做视频笔记时很实用。
这三类不是互相排斥的，很多扩展会同时提供多种打开方式。我常用的方案是优先选 Custom Editor 类的扩展，因为它能跟文件关联配合，双击即播，最符合日常操作习惯。
2. 第一步：挑选视频扩展，别只盯着下载量
2.1 主流视频扩展对比
VS Code 扩展商店里跟视频相关的扩展不少，但质量参差不齐，有的半年不更新，有的安装包捆绑了一堆用不上的功能。我花了一晚上把下载量靠前的几个都试了一遍，筛选标准有三个：
- 更新时间是否在一年以内，太老的基本不兼容新版 VS Code；
- 是否支持常见格式（MP4、WebM、MOV、MKV）；
- 是否提供快捷键、倍速、字幕等基础控制能力。
下面这个表格是我实测下来比较靠谱的几类扩展方向，注意我这里用的是扩展类型名，你在商店里搜索时建议加上最新更新时间排序：
| 扩展类型 | 适合场景 | 格式支持 | 特色能力 |
|---|---|---|---|
| Custom Editor 型播放器 | 双击文件直接播放 | MP4、WebM、MOV | 文件关联、快捷键控制 |
| 独立播放面板型 | 边看边写代码、多视频对比 | 大部分浏览器开源格式 | 画中画、倍速、字幕 |
| Markdown 嵌入型 | 技术教程、视频笔记 | HTML5 video 支持的格式 | 文档内嵌播放、逐段标注 |
选择建议是：如果你只是偶尔在 VS Code 里看个演示视频，选 Custom Editor 型就够了；如果你是要做长期的“视频 + 代码”学习工作流，建议选独立播放面板型，因为画中画功能太实用了。
2.2 安装的三种姿势：界面、命令行、离线 VSIX
安装扩展的方法很简单，但不同场景下效率差很多，我挨个说。
第一种，最常规的：打开 VS Code 左侧扩展面板，搜索关键词video player或者media player，找到合适的扩展后点击 Install。这种方式适合初次尝试，能在安装前看到扩展的评分、下载量和最近更新日期。
第二种，命令行安装。如果你知道自己要装的扩展 ID，可以直接在终端里运行：
code --install-extension publisher-name.extension-name比如某个扩展的 ID 是tomoki1207.mediaplayer（这里只是格式示例），安装命令就是：
code --install-extension tomoki1207.mediaplayer命令行安装的好处是干净快速，而且适合你管理的多台机器需要统一扩展环境时。
第三种，离线 VSIX 安装。有些内网开发环境无法访问扩展商店，需要先在能联网的机器上下载.vsix文件，然后拷贝到目标机器。在 VS Code 里按Ctrl+Shift+P，输入Install from VSIX，选择文件即可。这种方式我强烈建议配合扩展版本号一起记录，不然之后升级容易乱。
2.3 安装后的第一件事：确认扩展真的加载了
装完扩展不要急着打开视频，先在设置里搜索扩展名下相关的配置项。比如如果你装了一个名字里带video的扩展，按Ctrl+,打开设置，搜索video，如果能看到一堆扩展设置项，说明扩展已经正确加载并注册到了编辑器中。
这一步很重要。因为有些扩展安装后要求重启窗口才生效，如果你没重启，打开视频时可能会出现“无法打开此类型的文件”的提示。遇到这种情况，先执行命令Developer: Reload Window，或者直接重启 VS Code，90% 的问题都能解决。
离线安装相对容易踩一个坑：VSIX 包的版本和当前 VS Code 版本不兼容。VSIX 不支持跨大版本安装，比如你 VS Code 是 1.85，却装了一个要求 1.90 以上的扩展包，就会安装失败。所以离线安装时建议看准扩展的engines.vscode要求。
3. 第二步：让视频文件“认” VS Code：关联、打开与远程注意点
3.1 打开视频文件的三种顺手方式
扩展装好后，双击一个.mp4文件并不一定会自动用 VS Code 打开，因为系统的文件关联程序仍然是系统播放器。在 VS Code 里有三种方式可以强制用扩展打开视频：
- 在资源管理器中右键视频文件，选择
Open With...，然后从列表里选择刚装的视频播放器。 - 按
Ctrl+Shift+P打开命令面板，输入Open Video File或者其他扩展提供的打开命令，再选择文件。 - 直接把视频文件从系统文件管理器拖进 VS Code 编辑器区域，VS Code 会优先尝试用已注册的 Custom Editor 打开。
我个人最常用的是右键Open With...，因为可以顺带确认扩展是否真的被 VS Code 识别了。如果Open With...列表里没有视频播放器，说明扩展没有注册成功，先回去看第 2.3 节。
3.2 一劳永逸的文件关联配置
每次都右键Open With...太麻烦，正确做法是在settings.json里把视频格式默认关联到扩展。打开设置 JSON 的方式：Ctrl+Shift+P，输入Preferences: Open User Settings (JSON)，然后加上这样一段：
{ "workbench.editorAssociations": { "*.mp4": "yourVideoPlayer.customEditor", "*.webm": "yourVideoPlayer.customEditor", "*.mov": "yourVideoPlayer.customEditor" } }注意，yourVideoPlayer.customEditor这个 ID 要根据你装的扩展文档来替换，不同扩展的 ID 不一样。配置完成后，在资源管理器里双击视频文件，就会直接进入 VS Code 内置播放器。
这里有一个 VS Code 的细节值得说一下：编辑器关联分为预览模式（Preview）和持久模式。如果你在关联里指定了某个编辑器，双击文件默认以预览模式打开，这时候单击其他文件会替换当前视频标签；如果想让视频标签一直钉在那里，需要双击标签页标题或者右键选择Keep Open。在配置里也可以通过会话设置调整，但在 UI 上操作更直观。
3.3 远程开发、容器里播放视频时的性能差异
如果你像我一样经常用 VS Code 的 Remote-SSH 连到服务器上写代码，那么视频播放的表现会有明显不同。视频文件如果存放在远程服务器上，扩展播放视频时通常需要通过 VS Code 的远程通道把媒体数据传回本地 Webview 渲染，这个过程中局域网和跨公网的体验差异会非常大。
在局域网环境，播放一个几百 MB 的 MP4 基本无感，拖动进度条会有零点几秒的延迟；但如果远程服务器在公网另一端，网络延迟高，视频播放就会卡顿，尤其在拖进度条时特别明显。这不是扩展的问题，是远程架构决定的。
如果你要在远程环境里看视频，我的建议是：把视频文件放在本地，通过 VS Code 打开本地文件；或者在远程机器上直接挂载一个网络存储，减少一次性传输的数据量。此外再提一句，远程打开大视频文件时，尽量把 VS Code 的files.watcherExclude配置加上视频文件后缀，避免文件监听功能反复读取大文件，浪费 CPU。
4. 第三步：把播放器调到顺手：快捷键、倍速、字幕和画中画
4.1 常用播放控制的快捷键映射
很多视频扩展自带基本的播放控制按钮，但真正能提高效率的是把播放控制映射到键盘快捷键。我习惯的设置是这样的：
| 功能 | 默认键盘操作 | 我的自定义快捷键 |
|---|---|---|
| 播放 / 暂停 | 点击播放按钮或空格 | Space |
| 快进 10 秒 | 点击快进按钮 | Ctrl+Right |
| 快退 10 秒 | 点击快退按钮 | Ctrl+Left |
| 音量增减 | 点击音量条 | Ctrl+Up / Ctrl+Down |
| 切到画中画 | 点击 PiP 按钮 | Ctrl+Alt+P |
自定义快捷键要在keybindings.json里配置，格式大致是：
{ "key": "ctrl+alt+p", "command": "yourVideoPlayer.togglePictureInPicture", "when": "resourceExtname =~ /\\.(mp4|webm|mov)$/" }when条件是我特别想提的，它可以让快捷键只在打开视频文件时生效，避免和其他命令冲突。我在实际使用中遇到过很多次快捷键冲突：比如Ctrl+Alt+P在某些主题切换扩展里也有用途，这时候就需要在when里把范围缩小，或者干脆换一个组合键。
4.2 倍速播放和字幕加载
看技术录像、培训视频，倍速是刚需。主流视频扩展的设置项里一般会有defaultPlaybackRate，可以直接设为1.25或1.5，也可以在播放过程中按扩展提供的快捷键临时调整。
字幕支持方面，扩展通常会读取与视频同名的.vtt或.srt文件。比如demo.mp4旁边放一个demo.vtt，大部分扩展能在播放器里自动识别并显示字幕。如果你手里的字幕是.srt，建议用文本编辑器另存为 UTF-8 编码，否则在中文系统上可能出现字幕乱码。
4.3 画中画：边看视频边写代码的正确姿势
如果只能在 VS Code 里放视频，但一播放就盖住整个代码区，那意义不大。真正让我觉得“ VS Code 播放视频值了”的功能是画中画（Picture-in-Picture）。
开启画中画后，视频窗口会变成一个悬浮的小窗，置顶在 VS Code 窗口之上或者编辑器角落，你可以一边看视频一边操作其他面板、写代码、看调试输出，不需要来回切换窗口。实际用下来，我最常做的事就是把一个教学视频缩小放到右下角，然后左边编辑器对照着敲代码，效率比分开两个窗口高得多。
需要注意的一点是：画中画窗口是一个独立的原生窗口，在某些多显示器设备上可能出现位置偏移。如果你的扩展有画中画位置记忆功能，建议把位置固定到副屏，这样主屏幕仍然保留完整的代码工作区。
5. 播放失败排查链路：黑屏、无声、卡顿，一步步定位
5.1 排查步骤一：确认视频文件本身是“现代格式”
我先说一个很容易被忽略的事实：浏览器内核能播放的视频格式，并不等于你现在手里的所有视频格式。很多手机录屏、摄像机导出的视频是 H.265/HEVC 编码，虽然封装格式也许是.mp4，但浏览器内核默认不支持硬解 H.265，结果就是明明文件没坏，但 VS Code 里只出声不出画，或者干脆连声音都没有。
遇到这种情况，先用播放器确认文件本身是否正常。然后在终端里用 ffprobe 看一下真实编码：
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name -of default=noprint_wrappers=1 demo.mp4如果输出是hevc、av1这类编码，基本可以断定是解码兼容问题。解决方案有两个方向：
- 换一个支持更多编码格式的扩展，比如基于 mpv 内核的扩展，mpv 几乎是万能播放器；
- 用 ffmpeg 把视频转成 H.264 编码，这是最通用的浏览器兼容格式：
ffmpeg -i input.mp4 -c:v libx264 -profile:v high -pix_fmt yuv420p -c:a aac -movflags +faststart output.mp4-pix_fmt yuv420p这个参数尤其重要，很多浏览器播放器对 H.264+yuv420p 的支持是最稳妥的。如果你用默认参数转出来苹果设备上播放正常，但 Windows 上的 VS Code 黑屏，八成就是像素格式问题。
5.2 排查步骤二：黑屏、白屏的通用定位顺序
如果文件本身没问题，但打开后是黑屏或白屏，我的习惯是按以下顺序排查：
- 按
Ctrl+Shift+P，执行Developer: Reload Window，重新加载窗口； - 确认 VS Code 没有禁用了某个 Webview 相关的安全选项；
- 按
Ctrl+Shift+P，执行Developer: Toggle Developer Tools，打开开发者工具，查看 Console 标签里有没有红色报错； - 如果 Console 里出现
Not allowed to load local resource之类的错误，说明扩展访问本地文件受限，多数是权限或信任配置问题； - 尝试在 VS Code 设置里暂时关闭
window.titleBarStyle等窗口样式设置，某些自定义主题和视频渲染会有冲突。
实际遇到最多的情况是第三种：扩展更新版本后和旧版 VS Code 的 Webview API 不兼容。这种问题没有通用解法，只能回退到上一个扩展版本。
5.3 粉丝常问：有声无画、有画无声、拖动卡顿怎么破
| 现象 | 可能原因 | 解决方向 |
|---|---|---|
| 有声音无画面 | 视频编码为 HEVC/AV1，或像素格式不兼容 | 转码为 H.264 + yuv420p |
| 有画面无声音 | 音轨编码为 AC-3/DTS，浏览器不支持 | 转码音轨为 AAC |
| 拖动进度条卡顿 | 视频文件没有moov原子 | 用 ffmpeg 的-movflags +faststart重新封装 |
| 视频卡顿但 CPU 占用高 | 软件渲染，GPU 加速未开启 | 检查显卡驱动，开启硬件加速 |
| 打开后标签页一直在转圈 | 视频文件过大，Webview 加载慢 | 压缩分辨率或换成独立播放面板型扩展 |
这里单说“moov 原子”：MP4 文件的索引信息可以放在文件头部，也可以放在文件尾部。如果放在尾部（很多录屏软件默认这样），播放器必须先把整个文件读到底才能定位到关键帧，表现就是打开速度慢、拖动进度条卡。用上面提到的-movflags +faststart转码一遍，把索引挪到头部，问题立刻改善。
5.4 大文件播放卡顿的一种实用处理
如果一个视频本身有 4K/60 帧，体积好几个 GB，直接用 VS Code 的 Webview 播放确实会吃力，因为 Webview 本身就是浏览器渲染，不做硬解码优先级优化。
我有两个经验：
一是在扩展里找有没有“低分辨率预览”设置，有些扩展支持临时把视频解码分辨率降到 720P，够看清就行。
二是用 ffmpeg 做一个“看片用的压缩版”。不需要动原片，给同一个文件名加一个_preview后缀，一边看预览版，确认有用的部分再去原片里精修。
ffmpeg -i source.mkv -vf "scale=1280:720:force_original_aspect_ratio=decrease" -c:v libx264 -crf 28 -preset fast -c:a aac -movflags +faststart preview.mp46. 进阶用法：在 Markdown 里嵌视频、做视频笔记工作流
6.1 在 Markdown 文档中直接嵌入视频
视频扩展装好之后，其实还有一招隐藏玩法：利用 Markdown 预览把视频嵌进文档里。VS Code 的 Markdown 预览默认忽略 HTML 里的 video 标签，但部分扩展会接管预览渲染，让视频真正显示出来。
如果你用的是支持这一点的笔记类扩展，在 Markdown 里这样写：
<video controls width="720" src="./demo.mp4"></video>保存后打开 Markdown 预览，就能直接在文档里看到可播放的视频。这对我写技术教程特别实用，很多时候我想在文档里展示一段操作录屏，又不想单独开一个播放器窗口，直接在 Markdown 里嵌一个视频，读者打开预览就能看，省去大量切换成本。
需要提醒的是，嵌入的视频路径尽量使用相对路径，这样整个项目文件夹拷贝到别的机器上时，视频依然能找到。
6.2 视频 + 代码对照学习法
我现在的日常学习流是：左手边是教程视频，开启画中画缩小放到右下角；右手边是 VS Code 编辑器，跟着视频里的代码一步步敲。遇到视频里出现的重点内容，我会直接在 Markdown 里写笔记，视频的关键帧截图直接拖进笔记中。
有朋友问过我怎么在 VS Code 里截视频里的画面。两个办法：用系统截图工具截整个屏幕，或者用 ffmpeg 提取当前时间点的一帧：
ffmpeg -ss 00:12:34 -i demo.mp4 -frames:v 1 -q:v 2 frame.jpg这个办法适合在录屏视频里快速找到某个界面弹窗的画面，比反复拖动进度条找帧要高效很多。
如果你在这个工作流上再叠加一些 AI 编程助手插件，甚至可以让 AI 根据视频旁边贴的代码注释生成一份操作步骤清单，边看演示边自动整理文档，效果很直观。不过这属于锦上添花的部分，核心还是先把播放环境弄顺手。
6.3 我的实际使用心得
用了两个星期 VS Code 内嵌视频播放之后，我最直观的感受是：工具再多，不如少切换一次窗口。以前我在看技术视频和做笔记之间来回倒腾，注意力容易被打断，现在把视频固定在编辑器里，很多东西确实顺畅了不少。
如果你也想从系统播放器切到 VS Code 内嵌播放，我给个最小可行方案：装一个 Custom Editor 型视频扩展，把*.mp4和*.webm关联进去，然后把画中画快捷键设成你习惯的组合键，就够了。等用顺了再研究字幕、转码、Markdown 嵌入这些进阶功能。
如果你在配置过程中遇到了文章里没提到的问题，可以把开发者工具里的 Console 报错信息当成第一条线索，几乎所有播放异常都能从那里看到根因。祝顺利。
