如何让Paged.js交叉引用在VitePress中生效？

算力阿峰

2026-7-13

VitePress中Paged.js交叉引用（target-text）失效问题解决

问题现象

在VitePress里尝试用Paged.js的target-text CSS属性实现交叉引用，CSS样式已应用到目标链接，但预期的引用文本始终不显示。查看代码发现，原本的target-text被替换成了类似var(--pagedjs-088b62c0-38d2-499f-bf12-e82792a64fd8)的自定义变量。

原因分析

Paged.js处理交叉引用时，会把target-text属性动态转换为内部自定义变量，但VitePress的PostCSS构建流程或浏览器端脚本加载时机异常，导致变量未被填充为实际的引用文本。

解决步骤

加载完整的Paged.js浏览器脚本
不能只引入Paged.js的CSS，必须加载它的polyfill脚本才能让浏览器处理变量替换。在文档的脚本部分添加：
```
import 'pagedjs/dist/paged.polyfill.js';
```
确保CSS选择器和属性正确
目标元素需要设置唯一id，链接指向该id，同时添加注释避免预处理器转义target-text：
```
/* postcss-ignore */
a[href^="#"]::after {
  content: target-text(attr(href));
}
```

配置VitePress保留target-text属性
在vite.config.js中添加PostCSS插件，将被替换的变量还原为target-text：

export default {
  css: {
    postcss: {
      plugins: [
        {
          postcssPlugin: 'preserve-target-text',
          Declaration(decl) {
            if (decl.value.includes('var(--pagedjs-')) {
              decl.value = 'target-text(attr(href))';
            }
          }
        }
      ]
    }
  }
}

确保Paged.js在DOM加载后初始化
用Vue的onMounted钩子在DOM就绪后启动Paged.js渲染：

import { onMounted } from 'vue';
import Paged from 'pagedjs';

onMounted(() => {
  const pagedPreview = new Paged.Previewer();
  pagedPreview.preview();
});