在项目中使用 VitePress 作为文档常见问题：样式丢失，图标丢失，打包错误，中文配置修改等

本文总结和记录自己在使用 vitepress 作为 Vue 项目文档时遇到的问题，以及解决方法。直接进入正题：

md 文档中引入组件部分样式丢失

默认你导入的 vue 文件的 style 标签里的样式会生效，但是样式之外的样式不会生效，需要手动引入到，vitepress 主题中。

你不在 vue 文件中的样式都要引入，比如说：

• 你使用了 element-plus 的组件库，就需要手动引入他的 css 样式。
• 你自己写的 全局的 css 样式等，

具体做法就是：在 .vitpress 文件夹下新建 theme 文件夹 再在 theme 文件夹下新建 index.ts ，在 index.ts 文件中导入需要导入的样式。例如：

import "./src/styles/index.css";

在 md 文档中 import 的组件图标丢失

这个和上一个样式丢失一样，需要手动引入图标库 也是在 theme 文件夹下的 index.ts 中导入。这里有个坑，就是你在 main.ts 中是怎么让组件图标全局生效的就照样复刻一份，不可只引入图标，其实 vitepress 它本身就是和新开发一个 vue 项目原理类似，很多地方的思路都是相通的。例如导入 fontawesome 图标库 并使用添加 fas 包：

import { library } from "@fortawesome/fontawesome-svg-core";
import { fas } from "@fortawesome/free-solid-svg-icons";
library.add(fas);

如何把相关配置改为中文

这个是在 .vitepress 文件夹下的 config.ts 中配置 defineConfig 的 themeConfig 属性，具体配置如下：

export default defineConfig({
  themeConfig: {
    nav: [
      { text: "开始使用", link: "/introduce" },
      { text: "组件", link: "/components/button" }
    ],
    //开启本地搜索
    search: {
      provider: "local"
    },
    //修改侧边栏导航的标题
    outline: {
      label: "页面导航"
    },
    // 修改文档页脚的文字
    docFooter: {
      prev: "上一页",
      next: "下一页"
    },
    returnToTopLabel: "回到顶部",
    sidebarMenuLabel: "菜单",
    darkModeSwitchLabel: "主题",
    lightModeSwitchTitle: "切换到浅色模式",
    darkModeSwitchTitle: "切换到深色模式"
  }
});

打包不能识别.d.ts 文件

这个问题呢是，vitepress 默认是不识别双扩展名称的（根据我自己的试验是这样的，没有看到官方解释），比如像.d.ts 文件的，如果有其他解决方案欢迎留言交流，所以需要你在原组件中，把相关报错的文件名字写完整，比如说你在 Button.vue 中导入了一个 type.d.ts 文件，改正前是：

import type { ButtonProps } from "./type";

build 的时候提示了这里导入的文件找不到，你就修正，修正后：

import type { ButtonProps } from "./type.d.ts";

一般这个时候问题就解决了，如果还不行就把./type.d.ts路径名改成绝对路径，就是基于 src 的路径名，然后重新打包。

build 打包后直接访问 index.html 时样式和图标丢失

如果你build打包之前本地访问文档是正常的，打包后访问dist文件夹中的 index.html发现样式和图标丢失的话，这个其实不是 bug，因为 build 打包的 dist 文件默认并不是静态的，包括了 server 服务，如果你仔细 build 过程观察的话，在 build 的过程中的时候出现了

building client + server bundles...

所以打包的文件夹不是静态的，所以你访问 index.html 时，css 样式丢失。这个文件在你部署的时候就正常了，如果要访问具体效果，可以使用 vitepress 提供的访问命令，在本地预览生产版本：

npm run docs:preview

这样默认会在本地 4173 端口启动服务，浏览器打开就行了。

最后

有收获的话，欢迎点赞，收藏。本文讲解了自己在使用 vitepress 作为 Vue 项目文档时遇到的问题，以及解决方法。后续如果有其他问题和解决办法，我会继续更新。如果你在使用 vitepress 的时候遇到问题，欢迎留言交流。

后续更新的文章：
解决 VitePress 在 docs中vue 文件导入的 ts 类型的组件报错:Cannot find module…or its corresponding type declarations