企业官网建设流程全解析

• 前端
• 文档
• SSR

本指南基于 VuePress 官方仓库@vuepress/plugin-medium-zoom（1.9.10）的官方中文文档与其源码实现整理而成，覆盖安装、配置、选项说明与底层工作原理，帮助你在 VuePress 站点中一键实现 Medium 风格的点击图片放大预览效果。

插件能做什么

@vuepress/plugin-medium-zoom是 VuePress 官方插件之一，它基于社区成熟的 medium-zoom），为站点正文中的图片提供与 Medium 博客一致的点击放大（zoom）、移动端双击缩放、背景遮罩、ESC / 点击遮罩关闭等交互体验。它面向"文档型站点"场景，默认只作用于默认主题的正文内容区，不会影响导航栏、侧边栏等区域的图片，也不会劫持链接内图片的点击行为。

读完本文，你将掌握：如何安装并启用该插件、如何通过selector精确控制哪些图片可缩放、如何透传 medium-zoom 的原生选项（如margin）、以及插件在客户端混入（ClientRootMixin）中是如何实现"延迟初始化 + 路由切换后自动重建"这一核心机制的。

安装

插件作为独立的 npm 包发布，通过@vuepress/scope 引入。使用 Yarn 或 npm 将其安装为开发依赖：

yarn add -D @vuepress/plugin-medium-zoom # OR npm install -D @vuepress/plugin-medium-zoom

安装完成后，无需任何额外配置即可在.vuepress/config.js中启用。该插件依赖关系简单，仅包含@vuepress/types（用于类型标注）与medium-zoom两个依赖包，不会给构建带来额外负担。

使用

简单使用

在 VuePress 配置文件（.vuepress/config.js）的plugins数组中直接声明插件名即可：

module.exports = { plugins: ['@vuepress/medium-zoom'] }

这里使用的是插件短名称@vuepress/medium-zoom，VuePress 会自动解析到@vuepress/plugin-medium-zoom包。启用后，正文中的所有图片都会获得点击放大能力，无需修改任何 Markdown 内容。

自定义选项

当需要调整默认行为（例如只对特定图片生效，或修改放大动画参数）时，使用对象语法传入配置：

module.exports = { plugins: { '@vuepress/medium-zoom': { selector: 'img.zoom-custom-imgs', // medium-zoom options here options: { margin: 16 } } } }

对象写法支持两个顶层选项：selector（选择器）与options（medium-zoom 原生选项）。两者的详细说明见下文。

选项详解

插件对外暴露的选项非常克制，仅有两个：selector决定"缩哪些图"，options决定"怎么缩"。

selector

• 类型：string
• 默认值：.theme-default-content :not(a) > img

selector是一个 CSS 选择器，用于筛选哪些图片需要绑定缩放行为。

• 默认值拆解：.theme-default-content是默认主题为<Content />组件添加的 class name。也就是说，插件默认只对"正文内容区"内、且不是链接直接子元素的图片生效。:not(a) > img用于排除被<a>标签包裹的图片——这类图片通常本身带有跳转语义（如点击进入大图页），不应被缩放交互劫持。
• 自定义场景：如果你希望只缩放手动标记过的图片，可以像上文示例那样传selector: 'img.zoom-custom-imgs'，并在 Markdown 中给图片加上对应 class，例如图{.zoom-custom-imgs}；也可以扩展范围到整页，如selector: 'img'（不推荐，会覆盖导航栏 logo 等）。

实现细节：在 插件入口 中，selector通过define机制被编译为全局常量SELECTOR，未传时回退到默认值：

module.exports = (options, context) => ({ define: { SELECTOR: options.selector || '.theme-default-content :not(a) > img', OPTIONS: options.options }, clientRootMixin: path.resolve(__dirname, 'clientRootMixin.js') })

options

• 类型：object
• 默认值：undefined

options会被原样透传给 medium-zoom 实例（对应源码中的OPTIONS常量），用于控制缩放动画与弹层表现。medium-zoom 库内置了丰富的选项，常见且实用的有：

完整选项列表以 medium-zoom 库的官方 API 为准；在本仓库内，margin已在 官方文档示例 中被使用，是最典型的透传场景。

options默认值为undefined，即使用 medium-zoom 的默认行为（默认遮罩为半透明白色、无 margin 等）。

源码原理：插件是如何工作的

要理解该插件的行为特征（延迟 1 秒绑定、路由切换自动重建、z-index 修正），需要阅读它的三部分实现。

1. 插件入口：define 注入与 ClientRootMixin

插件入口 是一个标准的 VuePress 插件对象：

• 通过define把SELECTOR与OPTIONS注入为编译期全局常量，客户端代码可直接以全局变量方式使用（见clientRootMixin.js首行的/* global SELECTOR, OPTIONS */注释）；
• 通过clientRootMixin字段声明客户端根混入文件，实现"无侵入式"的全局能力注入，这也是官方插件为所有页面统一附加行为的标准做法。

2. 客户端混入：生命周期钩子 + 延迟刷新

clientRootMixin.js 是整个插件的核心逻辑所在：

export default { data: () => ({ zoom: null }), mounted () { this.updateZoom() }, updated () { this.updateZoom() }, methods: { updateZoom () { setTimeout(() => { if (this.zoom) { this.zoom.detach() } this.zoom = zoom(SELECTOR, OPTIONS) }, 1000) } } }

值得注意的实现要点：

• SSR 友好：由于 VuePress 页面在构建时经过 Node.js 服务端渲染（详见 在 Markdown 中使用 Vue），对浏览器/DOM API 的访问必须放在mounted之后。本插件将medium-zoom的实例化放在mounted/updated钩子中，且仅在客户端执行，因此与 SSR 完全兼容。
• 1 秒延迟初始化：setTimeout(..., 1000)是为了等待路由切换后页面 DOM 渲染稳定，避免在图片尚未插入时绑定失败。代价是页面加载后缩放能力有约 1 秒的"就绪窗口"。
• 先 detach 再重建：updateZoom每次都会先调用this.zoom.detach()解绑旧实例，再创建新实例。这一机制配合updated钩子，使得单页应用（SPA）内切换路由后，新页面的图片也能自动获得缩放能力，而不会出现旧绑定残留或新图片无响应的故障。

3. 样式修正：z-index 层级

style.css 针对默认主题对层级做了两处修正：

.medium-zoom-overlay { z-index: 100; } .medium-zoom-overlay ~ img { z-index: 101; }

• .medium-zoom-overlay是 medium-zoom 生成的遮罩层，z-index: 100使其覆盖在页面正文之上；
• .medium-zoom-overlay ~ img将被放大的图片提升到101，确保图片位于遮罩之上、可见且可交互。

这两条规则保证了在 VuePress 默认主题（侧边栏、导航栏均有较高层级定位）下，缩放弹层不会出现被其他元素遮挡的问题。

4. 与默认主题的配合

selector默认值中的.theme-default-content并非凭空而来——在默认主题的 Page.vue 与 Home.vue 中，<Content />组件均带有theme-default-contentclass；同时 config.styl 将其定义为样式变量$contentClass = '.theme-default-content'。因此插件默认选择器正好覆盖默认主题下所有页面正文（含首页）中的图片，开箱即用。

另外，默认主题在 index.js 中内置了@vuepress/active-header-links、@vuepress/search、@vuepress/plugin-nprogress等官方插件，但medium-zoom 并不在默认主题的默认插件列表中——它需要你显式配置启用，这一点与官方文档的说明一致。

最佳实践与常见问题

场景一：只缩放指定图片

文档中常有大图、截图需要放大，而装饰性图标不需要。此时应缩小选择范围：

module.exports = { plugins: { '@vuepress/medium-zoom': { selector: '.theme-default-content :not(a) > img.zoom-custom-imgs', options: { margin: 16 } } } }

并在 Markdown 中为目标图片打标：架构图{.zoom-custom-imgs}。

场景二：调整弹层观感

想让放大后的图片背景更"沉浸"，可配置遮罩颜色与边距：

module.exports = { plugins: { '@vuepress/medium-zoom': { options: { margin: 24, background: 'rgba(0, 0, 0, 0.9)' } } } }

常见问题

• 为什么链接内的图片不缩放？默认选择器:not(a) > img排除了<a>直接包裹的图片，避免点击图片触发缩放而非跳转。若你的文档大量使用"图片即链接"的写法，请显式调整selector。
• 为什么放大能力有约 1 秒延迟？这是clientRootMixin.js中 1 秒延迟策略的预期行为，用于等待 DOM 稳定；若你的页面图片加载较慢，可考虑自定义处理（该插件未开放延迟参数）。
• 自定义主题下没效果？默认选择器依赖默认主题的.theme-default-contentclass，使用自定义主题时需将selector改为你主题正文容器的 class。

小结

@vuepress/plugin-medium-zoom是一个"小而精"的官方插件：对外仅暴露selector与options两个选项，即可为 VuePress 正文图片提供完整的 Medium 风格缩放体验；对内则通过define常量注入、ClientRootMixin 生命周期钩子、延迟重建与 z-index 样式修正，优雅地解决了 SSR 兼容、SPA 路由切换与层级遮挡三类问题。阅读源码时建议以 插件入口、clientRootMixin.js 与 style.css 三个文件为线索，配合默认主题的 Page.vue 理解其设计意图。

• 前端
• 文档
• SSR