vuepress2.0搭建踩过的坑

柳儿
959 阅读4分钟

vuepress是什么？

官方文档快捷入口，自己看去！！

快速开始

环境要求：Node.js v14.18.0+
这个部分文档也都有就是这么简单

# 步骤 1: 创建并进入一个新目录
mkdir vuepress-starter
cd vuepress-starter

# 步骤 2: 初始化项目
git init
npm init

# 步骤3: 安装依赖
npm install -D vuepress@next

# 步骤 4: 在 package.json 中添加一些 scripts
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

# 步骤 5: 将默认的临时目录和缓存目录添加到 .gitignore 文件中
echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore

# 创建你的第一篇文档
mkdir docs
echo '# Hello VuePress' > docs/README.md

# 步骤 7: 在本地启动服务器来开发你的文档网站
npm run docs:dev

好叻！雏形有啦，来深入配置看看，让你的文档看起来更加优雅！！

文件目录结构说明

.
├── README.md
├── dist ---------------------------------- 打包后文件
├── docs ---------------------------------- vue组件和相关文档说明(docs是可以自定义的哦)
│   ├── .vuepress
│   ├── ├── components -------------------- vue组件
│   ├── ├── ├── Button.vue -------------------- vue组件
│   ├── ├── ├── Form 
│   ├── ├── ├── ├── Basic.vue -------------------- vue组件
│   ├── ├── public ------------------------ 静态文件夹
│   ├── ├── styles ------------------------ 全局样式文件 可以在这里修改主题
│   ├── ├── client.ts --------------------- 客户端配置文件 建议用`.ts`能够得到更好提示
│   ├── ├── config.ts --------------------- 配置文件
│   ├── README.md
│   └── framework ------------------------- 你的所有文档`framework`也是可以自定义的
│       ├── components
│       │   ├── button.md
│       │   ├── form
│       │   │   ├── api.md
│       │   │   └── index.md
│       └── guide
│           ├── changelog.md
│           ├── instroduction.md
├── package-lock.json
├── package.json
└── tsconfig.json

深入配置

以下提供最常用的配置及说明，其他自己看文档去。😡

config.ts 配置文件

// config.ts配置文件

// 配置文件
import { defaultTheme, defineUserConfig } from 'vuepress'
import { registerComponentsPlugin } from '@vuepress/plugin-register-components'
import { path, getDirname } from '@vuepress/utils'
const __dirname = getDirname(import.meta.url)

export default defineUserConfig({
// 语言 默认是en-US
  lang: 'zh-CN',
  // 标题
  title: '织女UI',
  description: 'WEBUI组件库',
  // 基础路径
  base: '/',
  // 渲染在HTML <head>标签内的额外内容
  head: [
    [
      'link',
      {
        rel: 'icon',
        href: '/logo.png',
      },
    ],
  ],
  // dev配置项 指定开发服务器的主机名
  host: '0.0.0.0',
  // 指定开发服务器的端口默认8080
  port: 9003,
  // 指定vuepress build命令的输出目录
  dest: './dist',
  // 自定义主题配置
  theme: defaultTheme({
  // 导航栏配置
    navbar: [
      { text: '主页', link: '/' },
      { text: '指南', link: '/framework/guide/development.md' },
      { text: '组件', link: '/framework/components/button.md' },
    ],
    // 侧边栏
    sidebar: [
      {
        text: '开始',
        collapsible: true,
        children: [
          { text: '快速开始', link: '/framework/guide/instroduction.md' },
          { text: '更新日志', link: '/framework/guide/changelog.md' }
        ],
      },
      {
        text: '基础',
        collapsible: true,
        children: [{ text: 'Button按钮', link: '/framework/components/button.md' }],
      },
      {
        text: '输入',
        collapsible: true,
        children: [
          {
            text: 'Form表单',
            link: '/framework/components/form/index.md',
            collapsible: true,
            children: [{ text: 'API', link: '/framework/components/form/api.md' }],
          },
        ],
      },
    sidebarDepth: 3,
  }),
  plugins: [
  // vue 组件全局注册，注册后的组件在markdown中既可以直接以标签方式渲染
  // 如以上目录结构中<Button/>渲染 ；嵌套文件则是<Form-Basic/>这种方式
    registerComponentsPlugin({
      componentsDir: path.resolve(__dirname, './components'),
    }),
  ]
})

client.ts客户端配置

一个基础的客户端配置文件是这样的

import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  rootComponents: [],
})

bug日志

1、SSR相关

一、现象

解决及原因

这是由于VuePress 会在构建过程中生成一个 SSR 应用，用以对页面进行预渲染。一般而言，如果一段代码在客户端应用 Mount 之前就使用了浏览器或 DOM API ，我们就认为其对 SSR 不友好，即不支持 SSR 。

官方提供两种方式解决：

  • ClientOnly 组件来包裹不支持 SSR 的内容。而当前是引人第三方vue组件库，在库中使用到了DOM API

  • 在 enhance 函数中，你可以使用 VUEPRESS_SSR 标记来处理这种情况。

// 客户端配置文件client.ts中
import { defineClientConfig } from '@vuepress/client'
import '@fzhx/znui/dist/style.css'

export default defineClientConfig({
  async enhance({ app, router, siteData }) {
    if (!__VUEPRESS_SSR__) {
      // __VUEPRESS_SSR__标识当前是否运行在服务端渲染 (SSR) 环境下，这个判断一定要用
      const znui = await import('@fzhx/znui')
      app.use(znui.default)
    }
  },
  setup() {},
  rootComponents: [],
})

二、现象

1.2、解决及原因

ssr相关enhance增强已配置但仍出现，定位到错误位置如上图。于是乎查看源码。比对不同版本区别（1.0.5之前打包ok, 升级到1.0.8出现）

谁成想竟然是因为tdesign源码导致的😷
v1.0.8时打包出现如上错误，估计是isUndefined相关问题
v1.0.5 以及v1.0.9 是相同的 说明1.0.8发现问题后官方偷偷修改了。不想说了😂

vuepress2.0 vs vuepress1.0

  • 如果你的项目是vue3.0开发的建议vuepress2.0能够得到更好的体验

  • 如果你的项目是vue2.0开发的建议用vuepress1.0

不同1: vuepress1.0中的SSR

在.vuepress/enhanceApp.js文件中进行处理

// import elementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({ Vue, options, router, siteData }) => {
  // Vue.use(elementUI)
  /**
   * 以下写法解决：build时，node.js没有document问题
   */
  Vue.mixin({
    mounted() {
      import(elementUI).then(function (m) {
        Vue.use(m.default)
      })
    },
  })
}

不同2: .vuepress/components/** 中组件会自定注册为全局组件

不同3: config.js主题配置方式

module.exports = {
  themeConfig: {
    //导航栏
    nav: [
      { text: '主页', link: '/' },
      { text: '指南', link: '/framework/guide/development.md' },
      { text: '组件', link: '/framework/comp/file-preview.md' },
    ],
    //侧边栏
    sidebar: [
      {
        title: '开发指南',
        collapsable: true,
        children: [
          ['/framework/guide/changelog.md', '更新日志'],
          ['/framework/guide/browser.md', '浏览器兼容性']
      },
      {
        title: '基础组件',
        collapsable: true,
        sidebarDepth: 2,
        children: [
          ['/framework/comp/button.md', 'Button按钮'],
        ],
      },
    ],
  }
}
avatar
文章
阅读
粉丝