VuePress的安装及设置

一、Node环境安装

1.进入Node官网，下载19.0.0版本，安装到Windows系统。 

https://nodejs.org

2.安装pnpm

npm install -g pnpm

安装以后，可以使用上述命令升级到最新版本。 

二、VuePress安装

进入vuepress的官网，按照指引安装。 

https://v2.vuepress.vuejs.org/

1.建立目录

mkdir vuepress-starter
cd vuepress-starter

2.初始化

git init
npm init

3.安装模块

(1)Vite打包工具

默认使用Vite打包工具，测试结果来看，Vite打包对PWA支持得不好。

首先，查看当前模块的最新版本 。

# vuepress的依赖项
pnpm view vue versions
pnpm view @vuepress/client versions
 
# 主模块
pnpm view vuepress versions

然后，安装最新版本模块。

# vuepress的依赖项
pnpm add -D vue@3.2.45
pnpm add -D @vuepress/client@next
 
# 主模块
pnpm add -D vuepress@next
 
# 子模块
pnpm add -D @vuepress/plugin-search@next        # 本地搜索功能
pnpm add -D @vuepress/plugin-pwa@next           # PWA功能
pnpm add -D @vuepress/plugin-pwa-popup@next     # PWA更新提示

对于@next的模块，如果未能安装最新版本，可在@后面直接添加最新版本号，替代next。一般显示如下： 

devDependencies:
+ @vuepress/plugin-search 2.0.0-beta.53 

不要尝试引用@vitejs/plugin-legacy模块，vue3不支持IE 11的，开发者应建议用户使用Edge、高版本的Chrome、Firefox等浏览器访问网站。

 (2)Webpack 打包工具

在(1)安装的基础上，按以下命令安装，使用Webpack打包工具，PWA功能正常。

首先，查看有关模块的最新版本。

# webpack的依赖项
pnpm view webpack versions
pnpm view sass-loader versions

然后，安装最新版本的相应模块。 

# webpack打包工具模块
pnpm add -D webpack@5.75.0
pnpm add -D sass-loader@13.2.0
pnpm add -D @vuepress/bundler-webpack@next      # Webpack 打包工具

config.ts中增加以下代码,可以使用webpack打包工具。 

import { webpackBundler } from '@vuepress/bundler-webpack'

  bundler: webpackBundler({
  postcss: {},
  vue: {},
  evergreen: false,
  }),

(3)查看已经安装的模块

pnpm list

显示如下： 

 devDependencies:
+ @vuepress/bundler-webpack 2.0.0-beta.53
+ @vuepress/client 2.0.0-beta.53
+ @vuepress/plugin-pwa 2.0.0-beta.53
+ @vuepress/plugin-pwa-popup 2.0.0-beta.53
+ @vuepress/plugin-search 2.0.0-beta.53
+ sass-loader 13.2.0
+ vue 3.2.45
+ vuepress 2.0.0-beta.53
+ webpack 5.75.0

4.在 package.json 中添加一些 scripts 

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

如果拷贝已有的 package.json 文件，可以直接执行以下命令

pnpm i

package.json内容如下： 

 {

  "name": "vuepress_pnpm",

  "version": "12.1.0",

  "description": "Vuepress",

  "main": "index.js",

  "scripts": {

    "docs:dev": "vuepress dev docs",

    "docs:build": "vuepress build docs"

  },

  "keywords": [],

  "author": "star",

  "license": "earth",

  "devDependencies": {

    "@vuepress/bundler-webpack": "2.0.0-beta.53",

    "@vuepress/client": "2.0.0-beta.53",

    "@vuepress/plugin-pwa": "2.0.0-beta.53",

    "@vuepress/plugin-pwa-popup": "2.0.0-beta.53",

    "@vuepress/plugin-search": "2.0.0-beta.53",

    "sass-loader": "13.2.0",

    "vue": "3.2.45",

    "vuepress": "2.0.0-beta.53",

    "webpack": "5.75.0"

  }

}

5.将默认的临时目录和缓存目录添加到 .gitignore 文件中

echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore

三、网站测试

1.拷贝源代码

将docs目录拷贝到vuepress-starter目录内，修改\docs\.vuepress目录内的config.ts文件，可修改网站内容。

//引入变量

import { defineUserConfig } from 'vuepress'
import { defaultTheme } from 'vuepress'
import { searchPlugin } from '@vuepress/plugin-search'
import { pwaPlugin } from '@vuepress/plugin-pwa'
import { pwaPopupPlugin } from '@vuepress/plugin-pwa-popup'
import { webpackBundler } from '@vuepress/bundler-webpack'

//主程序代码

export default defineUserConfig({

//基础设置

  base: '/',
  lang: 'zh-CN',
  title: '轻松报表',
  description: '轻松报表系列工具',

//webpcak打包设置

  bundler: webpackBundler({
  postcss: {},
  vue: {},
  evergreen: false,
  }),

//设置头部

	head: [
		['meta', { name: 'viewport', content: 'width=device-width,initial-scale=1,user-scalable=no' }],
		['link', { rel: 'icon', href: '/images/logo.ico' }],
   		['link', { rel: 'manifest', href: '/manifest.webmanifest' }],
  		['meta', { name: 'theme-color', content: '#3eaf7c' }],
	],

//插件设置

  plugins: [
 
    searchPlugin({
      locales: {
        '/': {
          placeholder: '搜索',
        },
      },
    }), 
   
    pwaPlugin({
      skipWaiting: true,
      serviceWorkerFilename: 'service-worker.js',
    }),
    
    pwaPopupPlugin({
      locales: {
        '/': {
          message: '发现新内容可用',
          buttonText: '刷新',
        },
      },
    }),
  ],
  
//默认主题设置

  theme: defaultTheme({
    home: '/', 
    logo: '/images/logo.png',
    navbar: [
      {
        text: '首页',
        link: '/',
      }, 
      { text: '入门', link: '/start/' },
    ],
    sidebar: {
      '/tutorial/': [
        {
          text: '教程',
          children: ['/tutorial/README.md'],
        },
      ],
      '/install/': [
        {text: '系统要求',
         collapsible: true,
         children: [
          '/install/README.md',
           ],
        },
    },
        // custom containers
        tip: '提示',
        warning: '注意',
        danger: '警告',
        // 404 page
        notFound: [
          '这里什么都没有',
          '我们怎么到这来了？',
          '这是一个 404 页面',
          '看起来我们进入了错误的链接',
        ],
    backToHome: '返回首页',
    // a11y
    openInNewWindow: '在新窗口打开',
    toggleColorMode: '切换日夜模式',
    toggleSidebar: '切换侧边栏',
  }),


})

 

2.运行调试

pnpm run docs:dev

四、生成网站打包

运行以下命令，生成的代码在\docs\.vuepress\dist目录中，拷贝至web服务器中。

pnpm run docs:build