我的网站是用vitepress搭建的，在撰写技术文档时，我们经常需要插入 YouTube 视频教程。
很多站长习惯直接复制 YouTube 提供的 代码粘贴到 Markdown 里。虽然能用，但缺点很明显：
-
代码丑陋：文章里充斥着一大段 HTML 代码，难以维护。
-
手机端体验差：固定宽高导致在手机上视频显示不全，或者比例失调。
今天，我将分享一种 “优雅专业法”，通过封装 Vue 组件，实现一次配置，处处调用，且完美适配移动端。同时，我会重点讲解在自定义主题结构下，如何解决引用路径报错的问题。
第一步：封装响应式视频组件
我们需要创建一个专门的组件，利用 CSS 技巧让视频保持 16:9 的黄金比例，并自适应屏幕宽度。
1. 创建组件文件
建议将组件放在主题文件夹下的组件目录中，这样结构更清晰。
 |
| 需要注意文件路径 |
推荐路径： docs/.vitepress/theme/components/YouTube.vue
(如果没有 components 文件夹，请手动新建)
代码内容 (YouTube.vue)：
 |
| 代码段 |
<script setup>
defineProps({
id: {
type: String,
required: true
}
})
</script>
<template>
<div class="youtube-container">
<iframe
:src="'https://www.youtube.com/embed/' + id"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen
></iframe>
</div>
</template>
<style scoped>
.youtube-container {
position: relative;
width: 100%;
padding-bottom: 56.25%; /* 核心：通过 padding 实现 16:9 比例 */
height: 0;
overflow: hidden;
margin: 16px 0;
border-radius: 8px; /* 圆角设计，更具现代感 */
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}
.youtube-container iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
</style>
第二步：全局注册 (避坑关键点！)
这是很多新手最容易报错的一步：Cannot find module。
这通常是因为 theme/index.ts 引用组件时的相对路径写错了。
场景还原
你的文件结构应该是这样的：
|
| 文件路径不同，引入就不同 |
docs/
└── .vitepress/
└── theme/
├── index.ts <-- 我们在这里写注册代码
└── components/ <-- 组件文件夹在这里
└── YouTube.vue
正确的注册代码
因为 index.ts 和 components 文件夹是同级的，所以引用路径必须使用 ./ 而不是 ../。
修改文件： docs/.vitepress/theme/index.ts
 |
| 组件引入与注册 |
TypeScript
import DefaultTheme from 'vitepress/theme'
// 👇 关键：注意这里的路径是 ./components
import YouTube from './components/YouTube.vue'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// 注册全局组件
app.component('YouTube', YouTube)
}
}
💡 提示： 修改了
index.ts后，如果页面没有生效或报错，请尝试在终端按Ctrl + C停止服务，然后重新运行npm run docs:dev重启开发服务器。
第三步：在文章中优雅调用
现在，你可以在任何 Markdown (.md) 文件中直接使用这个组件了。不需要写复杂的 HTML，只需要填入视频 ID。
什么是视频 ID？
如果是 https://www.youtube.com/watch?v=mev07rNC8Sc，ID 就是 mev07rNC8Sc。
Markdown 写作示例：
 |
| Markdown 写作示例 |
## 视频教程
这里是本期关于免费机场注册的视频教程：
<YouTube id="mev07rNC8Sc" />
这样渲染出来的视频，无论是在 27 寸的显示器上，还是在 6 寸的手机屏幕上，都能保持完美的比例和圆角效果。
🎁 进阶建议：Video SEO 策略
作为内容创作者，只放视频是不够的。搜索引擎（Google/Bing）的爬虫看不懂视频内容。
为了让你的文章获得更好的排名，建议采用 “视频 + 文字总结” 的结构：
-
开头：放置
<YouTube />组件，直观展示。 -
正文：紧接着写一段 200-300 字的“视频精华文字版”。
- 例如：“在视频 02:15 处，我演示了如何注册xxx网站用户，这里需要注意区分大小写…”
这样做，既照顾了喜欢看视频的用户，也能让搜索引擎的爬虫喜欢爬取，能极大增加关键词收录概率。
希望这篇教程能帮助大家打造更专业的文档站点！
