叁聖涅前置知识
关于包管理器
npm：npm（Node Package Manager）是Node.js的默认包管理器。它是一个全球最大的开源软件注册表，拥有数量庞大的包供开发者使用。npm具有广泛的生态系统和大量的社区支持。
- 优点：软件包数量庞大，几乎包含了所有常见的开源库和工具。 社区活跃，有大量的文档、教程和支持。 可以方便地管理项目依赖和版本控制。 提供了一些实用的命令和功能，如脚本执行、版本管理等。
- 缺点：安装包的速度较慢，特别是在网络不稳定的情况下。 包的安装和更新可能会产生冲突或版本不一致的问题。 依赖关系管理相对较弱，可能会导致包冲突或依赖关系混乱。
bash[root@vp vitepress-starter]# dnf list npm* Last metadata expiration check: 0:16:02 ago on Fri Jan 12 11:16:33 2024. Available Packages npm.x86_64 1:8.19.4-1.16.20.2.3.el9_2 appstreamyarn：yarn是由Facebook开发的另一个包管理器，旨在解决npm在性能和一致性方面的一些问题。它使用与npm相同的包注册表。
- 优点：安装速度更快，通过并行安装和缓存机制优化了性能。 锁定依赖版本，确保在不同环境中安装相同的包版本。 更好的对冲突解决方案的支持。
- 缺点：需要额外的安装步骤，与npm相比，使用上有一定的学习曲线。 对于某些特定的项目或场景，可能与npm存在不兼容性。
bash# 可以运行以下命令 安装 和 更新 Yarn： npm install --global yarn # 卸载 npm uninstall -g yarncnpm：cnpm是淘宝镜像团队提供的npm镜像，它允许在中国境内更快地安装和下载npm包。cnpm使用与npm相同的命令行接口。
pnpm：pnpm是另一种包管理器，它通过共享相同的依赖项来减少磁盘空间的占用。它使用硬链接或符号链接来共享依赖项。
- 优点：节省磁盘空间，因为共享相同的依赖项只占用一次磁盘空间。 安装速度更快，因为不需要重复安装相同的依赖项。 强大的依赖关系管理，可以避免版本冲突和不一致性。
- 缺点：需要额外的安装步骤，与npm相比，使用上有一定的学习曲线。 不支持所有npm命令和功能。
bashnpm install -g pnpm pnpm init
nmp常用指令
bash
# 更换为国内源
npm config set registry https://registry.npmmirror.com
npm config set registry https://registry.npmjs.org/
# 查看当前源
npm config get registry
# 升级npm版本
npm i -g npm
# 升级到指定版本
npm i -g npm@6.0.0yarn常用指令
bash
yarn -v # 查看yarn 版本
yarn config list # 查看yarn配置
yarn config get registry # 查看当前yarn源
# 忽略引擎检查(例如node版本不匹配)
yarn install --ignore-engines
yarn global add <your app> --ignore-engines
# 修改yarn源（此处为淘宝的源）
yarn config set registry https://registry.npmmirror.com
# yarn安装依赖
yarn add 包名 # 局部安装
yarn global add 包名 # 全局安装
# yarn 卸载依赖
yarn remove 包名 # 局部卸载
yarn global remove 包名 # 全局卸载（如果安装时安到了全局，那么卸载就要对应卸载全局的）
# yarn 查看全局安装过的包
yarn global list
# 安装yarn
npm install -g yarn
yarn --version # 安装成功后，查看版本号
md yarn # 创建文件夹 yarn
cd yarn # 进入yarn文件夹
# 初始化项目，同npm init，执行输入信息后，会在当前目录中生成package.json文件
yarn init
# yarn的配置项：
yarn config list # 显示所有配置项
yarn config get <key> # 显示某配置项
yarn config delete <key> # 删除某配置项
yarn config set <key> <value> [-g|--global] # 设置配置项
yarn config set ignore-engines true # 例如设置忽略引擎检查
# 安装包：
yarn install # 安装package.json里所有包，并将包及它的所有依赖项保存进yarn.lock
yarn install --flat # 安装一个包的单一版本
yarn install --force # 强制重新下载所有包
yarn install --production # 只安装dependencies里的包
yarn install --no-lockfile # 不读取或生成yarn.lock
yarn install --pure-lockfile # 不生成yarn.lock
# 添加包（会更新package.json和yarn.lock）：
yarn add [package] # 在当前的项目中添加一个依赖包，会自动更新到package.json和yarn.lock文件中
yarn add [package]@[version] # 安装指定版本，这里指的是主要版本，如果需要精确到小版本，使用-E参数
yarn add [package]@[tag] # 安装某个tag（比如beta,next或者latest）
# 不指定依赖类型默认安装到dependencies里，你也可以指定依赖类型：
yarn add --dev/-D # 加到 devDependencies
yarn add --peer/-P # 加到 peerDependencies
yarn add --optional/-O # 加到 optionalDependencies
# 默认安装包的主要版本里的最新版本，下面两个命令可以指定版本：
yarn add --exact/-E # 安装包的精确版本。例如yarn add foo@1.2.3会接受1.9.1版，但是yarn add foo@1.2.3 --exact只会接受1.2.3版
yarn add --tilde/-T # 安装包的次要版本里的最新版。例如yarn add foo@1.2.3 --tilde会接受1.2.9，但不接受1.3.0
yarn publish # 发布包
yarn remove <packageName> # 移除一个包，会自动更新package.json和yarn.lock
yarn upgrade # 更新一个依赖: 用于更新包到基于规范范围的最新版本
yarn run # 运行脚本: 用来执行在 package.json 中 scripts 属性下定义的脚本
yarn info <packageName> # 可以用来查看某个模块的最新版本信息
# 缓存
yarn cache
yarn cache list # 列出已缓存的每个包
yarn cache dir # 返回 全局缓存位置
yarn cache clean # 清除缓存Linux更换node及npm版本
提示
rockly9.2中使用dnf安装npm时，默认的node版本为v16，此时使用yarn部署vitepress时会提示node版本过低。
sh
[root@vp vp]# yarn add --dev vitepress
yarn add v1.22.21
info No lockfile found.
[1/4] Resolving packages...
[2/4] Fetching packages...
error @vitejs/plugin-vue@5.0.3: The engine "node" is incompatible with this module. Expected version "^18.0.0 || >=20.0.0". Got "16.20.2"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.node升级
node可以使用n来进行node和mpm的升级。n是node的一个版本工具首先安装n工具：
bash
root@vp vitepress-starter]# npm install -g n
added 1 package in 2s
[root@vp vitepress-starter]#
[root@vp vitepress-starter]# n --version
v9.2.0
[root@vp vitepress-starter]#n命令行帮助
bash
[root@vp vitepress-starter]# n --help
Usage: n [options] [COMMAND] [args]
Commands:
n Display downloaded Node.js versions and install selection
n latest Install the latest Node.js release (downloading if necessary)
n lts Install the latest LTS Node.js release (downloading if necessary)
n <version> Install Node.js <version> (downloading if necessary)
n install <version> Install Node.js <version> (downloading if necessary)
n run <version> [args ...] Execute downloaded Node.js <version> with [args ...]
n which <version> Output path for downloaded node <version>
n exec <vers> <cmd> [args...] Execute command with modified PATH, so downloaded node <version> and npm first
n rm <version ...> Remove the given downloaded version(s)
n prune Remove all downloaded versions except the installed version
n --latest Output the latest Node.js version available
n --lts Output the latest LTS Node.js version available
n ls Output downloaded versions
n ls-remote [version] Output matching versions available for download
n uninstall Remove the installed Node.js
Options:
-V, --version Output version of n
-h, --help Display help information
-p, --preserve Preserve npm and npx during install of Node.js
-q, --quiet Disable curl output. Disable log messages processing "auto" and "engine" labels.
-d, --download Download if necessary, and don't make active
-a, --arch Override system architecture
--offline Resolve target version against cached downloads instead of internet lookup
--all ls-remote displays all matches instead of last 20
--insecure Turn off certificate checking for https requests (may be needed from behind a proxy server)
--use-xz/--no-use-xz Override automatic detection of xz support and enable/disable use of xz compressed node downloads.
Aliases:
install: i
latest: current
ls: list
lsr: ls-remote
lts: stable
rm: -
run: use, as
which: bin
Versions:
Numeric version numbers can be complete or incomplete, with an optional leading 'v'.
Versions can also be specified by label, or codename,
and other downloadable releases by <remote-folder>/<version>
4.9.1, 8, v6.1 Numeric versions
lts Newest Long Term Support official release
latest, current Newest official release
auto Read version from file: .n-node-version, .node-version, .nvmrc, or package.json
engine Read version from package.json
boron, carbon Codenames for release streams
lts_latest Node.js support aliases
and nightly, rc/10 et al
[root@vp vitepress-starter]#升级node到最新版本
bash
[root@vp vitepress-starter]# n latest
installing : node-v21.5.0
mkdir : /usr/local/n/versions/node/21.5.0
fetch : https://nodejs.org/dist/v21.5.0/node-v21.5.0-linux-x64.tar.gz
copying : node/21.5.0
installed : v21.5.0 (with npm 10.2.4)
Note: the node command changed location and the old location may be remembered in your current shell.
old : /usr/bin/node
new : /usr/local/bin/node
If "node --version" shows the old version then start a new shell, or reset the location hash with:
hash -r (for bash, zsh, ash, dash, and ksh)
rehash (for csh and tcsh)
[root@vp vitepress-starter]# node --version
v16.20.2
[root@vp vitepress-starter]#
# 启动一个新shell
[root@vp ~]# node --version
v21.5.0
[root@vp ~]#删除某个版本
bash
n rm 10.13.0多版本切换
bash
[root@vp ~]# n # 如果存在多个版本，则可以使用上下箭头选择
/usr/local/bin/n: line 539: clear: command not found
node/21.5.0
Use up/down arrow keys to select a version, return key to install, d to delete, q to quit/usr/local/bin/n: line 562: clear: command not found
ο node/21.5.0
Use up/down arrow keys to select a version, return key to install, d to delete, q to quit/usr/local/bin/n: line 567: clear: command not found
ο node/21.5.0
Use up/down arrow keys to select a version, return key to install, d to delete, q to quit/usr/local/bin/n: line 608: clear: command not found
[root@vp ~]#准备工作
node.js是JavaScript的运行环境
- 官网：https://nodejs.org/zh-cn/
- 仓库：https://github.com/nodejs/node
- Node.js 18 及以上版本。但是使用pnpm安装以来的时候却没有这个版本要求
- 手动安装Nodejs的参考
提示
使用包管理器部署vitepress时无需手动安装nodejs
部署VitePress
提示
以下内容和过程步骤仅在rockly9.2中测试通过。
- 创建并进入目录bash
mkdir /vp && cd /vp - 安装
npmbash# 安装npm(node package management) dnf install -y npm # 设置npm源 npm config set registry https://registry.npmmirror.com - 安装{pnpm|yarn|bun},选择其一即可sh
npm install -g pnpmshnpm install --global yarn # yarn并不共享npm的源，因此还需要手动改为国内 [root@vp vp]# yarn config get registry https://registry.yarnpkg.com [root@vp vp]# yarn config set registry https://registry.npmmirror.com yarn config v1.22.21 success Set "registry" to "https://registry.npmmirror.com". Done in 0.14s. [root@vp vp]# yarn config get registry https://registry.npmmirror.com [root@vp vp]#shnpm install --global bun - 安装依赖
提示
注意：安装依赖时应该位于
/vp目录下。 如果选择使用yarn，则可能需要先升级node版本shnpm i -D vitepressshpnpm add -D vitepressshyarn add --dev vitepressshbun add --dev vitepress收到了缺少对等依赖的警告
如果使用 PNPM，您会注意到 @docsearch/js 缺少对等警告。这并不妨碍 VitePress 工作。如果您希望抑制此警告，请将以下内容添加到您的 package.json
注意：最新版已经不会提示了！
json"pnpm": { "peerDependencyRules": { "ignoreMissing": [ "@algolia/client-search", "search-insights" ] } }信息
VitePress是一个仅支持ESM的软件包。不要使用 require() 来导入它，并确保您最近的 package.json 文件包含 "type": "module" ，或者将相关文件的扩展名例如 vitepress/config.js 更改为.mjs/.mts。有关更多详细信息，请参考 Vite的故障排除指南 。此外，在异步的CJS上下文中，您可以使用 await import('vitepress') 来代替。
- 初始化向导sh
npx vitepress initshpnpm vitepress init # or pnpm dlx vitepress init # 如果使用pnpm初始化，则：回答以下问题 [root@vp vp]# pnpm vitepress init ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # 手动指定文档根目录 # 如果正在构建一个独立的 VitePress 站点，可以在当前目录 (`./`) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 `./docs`) 中，以便它与项目的其余部分分开。 ◇ Site title: │ My Awesome Project │ ◇ Site description: │ A VitePress Site │ ◇ Theme: │ Default Theme │ ◇ Use TypeScript for config and theme files? │ Yes │ ◇ Add VitePress npm scripts to package.json? │ Yes │ └ Done! Now run pnpm run docs:dev and start writing. # 假设选择在 `./docs` 中搭建 VitePress 项目，生成的文件结构应该是这样的： [root@vp vp]# pwd /vp [root@vp vp]# tree -a ./docs/ . ├─ docs # docs 目录作为 VitePress 站点的项目根目录。 │ ├─ .vitepress # `.vitepress`目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。 │ │ └─ config.js │ ├─ api-examples.md │ ├─ markdown-examples.md │ └─ index.md └─ package.json [root@vp vp]#shyarn vitepress init [root@vp vp]# yarn init yarn init v1.22.21 warning package.json: No license field question name (vp): question version (1.0.0): question description: docs question entry point (index.js): question repository url: question author: question license (MIT): question private: success Saved package.json Done in 60.62s. [root@vp vp]# pwd /vp [root@vp vp]# ll -a total 44 drwxr-xr-x. 3 root root 63 Jan 15 12:45 . drwxr-xr-x. 1 root root 83 Jan 15 12:40 .. drwxr-xr-x. 36 root root 4096 Jan 15 12:45 node_modules -rw-r--r--. 1 root root 168 Jan 15 12:47 package.json -rw-r--r--. 1 root root 35840 Jan 15 12:45 yarn.lock [root@vp vp]# cat package.json { "devDependencies": { "vitepress": "^1.0.0-rc.36" }, "name": "vp", "version": "1.0.0", "description": "docs", "main": "index.js", "license": "MIT" } [root@vp vp]#shbunx vitepress init提示
如果使用
pnpm进行初始化，则默认会部署目录结构和必要的配置文件，初始化完成之后即可启动和运行，或跳转到步骤8。 如果使用yarn进行初始化，则继续进行后续步骤。提示
Vue 作为对等依赖
如果您打算使用 Vue 组件或 API 进行自定义，您还应该显式安装 vue 作为对等依赖项。
shpnpm add -D vue提示
默认情况下，VitePress 将其开发服务器缓存存储在
.vitepress/cache中，并将生产构建输出存储在.vitepress/dist中。如果使用 Git，应该将它们添加到.gitignore文件中。也可以手动配置这些位置。 - 创建一个测试首页bash
[root@vp vp]# mkdir docs && echo '# Hello VitePress' > docs/index.md [root@vp vp]# - 在
package.json.添加script部分bash# 在 package.json 中增加打包以及运行的指令。 [root@vp vp]# cat package.json { "devDependencies": { "vitepress": "^1.0.0-rc.36" }, "name": "vp", "version": "1.0.0", "description": "docs", "main": "index.js", "license": "MIT", "scripts": { "docs:dev": "vitepress dev docs", # 本地运行测试 "docs:build": "vitepress build docs", # 项目打包：最终结果会在 .vitepress/ dist 中 "docs:serve": "vitepress serve docs" # 预览打包后的效果，此命令只有 build 成功 后才会执行成功。 } } [root@vp vp]# # 添加"type": "module" # 如果不添加module，则config.js中的export指令可能无法使用 - 启动
从 VuePress 迁移至 VitePress
安装依赖
- node 18.x
- pnpm 7.x
- vitepress 1.0.0-alpha.46
- vue 3.2.47
- vuepress 2.0.0-beta.60 （标注之前用的 VuePress 版本）
创建 .npmrc 文件，配置内容如下（不使用 pnpm 的可以忽略）
sh
auto-install-peers=true
registry=https://registry.npmmirror.com安装 vitepress 相关依赖
sh
pnpm add -D vitepress vue修改 package.json 中的 scripts
sh
# dev 命令
npm pkg set scripts.dev="vitepress dev docs --port=8732"
# build 命令
npm pkg set scripts.build="vitepress build docs"注意点
vitepress修改启动端口需要通过命令行传参--port=8732public公共文件vuepress是docs/.vuepress/public目录vitepress是docs/public目录
- 路由
vuepress默认配置下README.md和index.md都会被转换成index.htmlvitepress默认配置下只有index.md会被转换成index.html
vuepress使用的是navbar，需要修改为navvuepress使用的是children，需要修改为items，且items是一个对象数组vuepress sidebar的展开使用的是collapsible，需要修改为collapsed- 导入代码块
vuepress- 语法为
@[code](./code/snippet.js)
- 语法为
vitepress- 语法为
<<< @/code/snippet.js - 部分导入使用
VS Code region语法，不再支持按行号引入
- 语法为
快速修改 README.md 为 index.md
安装 globby
sh
pnpm add -D globby编写重命名脚本
ts
import { globby } from 'globby'
import fs from 'node:fs'
const paths = await globby(['docs/**/README.md'])
paths.forEach((path) => {
fs.rename(path, path.replace(/README\.md/, 'index.md'), (err) => {
!err && console.log(`${path} 重命名成功`)
})
})配置语法对比
ts
/* vuepress 写法 */
export default {
themeConfig: {
navbar: [
{ text: 'Guide', link: '/guide' },
{
text: 'Dropdown Menu',
children: ['/item-1.md']
}
],
sidebar: {
'/guide/': [
{
text: 'Guide',
collapsible: true,
children: ['/item-1.md']
}
]
}
}
}
/* vitepress 写法 */
export default {
themeConfig: {
nav: [
{ text: 'Guide', link: '/guide' },
{
text: 'Dropdown Menu',
items: [{ text: 'Item A', link: '/item-1' }]
}
],
sidebar: {
'/guide/': [
{
text: 'Guide',
collapsed: false,
items: [{ text: 'Index', link: '/guide/' }]
}
]
}
}
}配置 vitepress
在 docs/.vitepress 目录下创建 config.ts 文件
ts
import { defineConfig } from 'vitepress'
export default defineConfig({
// 打包输出目录
outDir: '../dist',
// 站点语言标题等
lang: 'zh-CN',
title: '茂茂物语',
description: '茂茂的成长之路，包含前端常用知识、源码阅读笔记、各种奇淫技巧、日常提效工具等',
/* 主题配置 */
themeConfig: {
i18nRouting: false,
logo: '/logo.png',
nav: [],
sidebar: {},
/* 右侧大纲配置 */
outline: {
level: 'deep',
label: '本页目录'
},
socialLinks: [{ icon: 'github', link: 'https://github.com/maomao1996' }],
footer: {
copyright: 'Copyright © 2019-present maomao'
},
darkModeSwitchLabel: '外观',
returnToTopLabel: '返回顶部',
lastUpdatedText: '上次更新',
docFooter: {
prev: '上一篇',
next: '下一篇'
}
}
})添加自定义样式
在 docs/.vitepress/theme 目录下创建 index.ts 文件和 index.css
index.ts 文件内容如下
ts
import Theme from 'vitepress/theme'
import './index.css'
export default Theme通过插槽添加自定义组件
提示
这里用一个访问统计来举 🌰
配置 TS 环境
创建 tsconfig.json
json
{
"compilerOptions": {
"outDir": "dist",
"target": "esnext",
"module": "esnext",
"moduleResolution": "node",
"esModuleInterop": true,
"resolveJsonModule": true,
"allowJs": true,
"strict": true,
"jsx": "preserve"
},
"include": ["env.d.ts", "**/.vitepress/**/*"]
}创建 env.d.ts
ts
/// <reference types="vitepress/client" />
declare module '*.vue' {
import { DefineComponent } from 'vue'
const component: DefineComponent<{}, {}, any>
export default component
}编写 Visitor 组件
在目录 docs/.vitepress/theme/components 下创建 Visitor.vue 文件
vue
<script setup lang="ts">
import { useRoute } from 'vitepress'
const route = useRoute()
</script>
<template>
<img
class="visitor"
:src="`https://visitor-badge.laobi.icu/badge?page_id=你的个人标识&p=${route.path}`"
onerror="this.style.display='none'"
/>
</template>
<style scoped>
.visitor {
margin-left: 8px;
}
@media (min-width: 768px) and (max-width: 920px) {
.visitor {
display: none;
}
}
</style>修改 docs/.vitepress/theme/index.ts 文件
ts
import { h, App } from 'vue'
import Theme from 'vitepress/theme'
import Visitor from './components/Visitor.vue'
import './styles/index.scss'
export default Object.assign({}, Theme, {
Layout: () =>
h(Theme.Layout, null, {
/**
* 相关插槽
* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/Layout.vue
*/
'nav-bar-title-after': () => h(Visitor)
})
})测试案例-使用pnpm
从头开始搭建一个简单的 VitePress 文档站点。如果你已经有了一个存在的项目并且向在项目中维护文档，你可以从步骤 3 开始。
步骤 1: 创建并进入一个目录
bash[root@vp ~]# mkdir /vitepress-starter && cd /vitepress-starter [root@vp vitepress-starter]# # 安装npm dnf install -y npm # 设置npm源 npm config set registry https://registry.npmmirror.com步骤 2: 初始化
bash# pnpm [root@vp vitepress-starter]# npm install --global {yarn|pnpm|cnpm} added 1 package, and audited 2 packages in 6s found 0 vulnerabilities npm notice npm notice New major version of npm available! 8.19.4 -> 10.3.0 npm notice Changelog: https://github.com/npm/cli/releases/tag/v10.3.0 npm notice Run npm install -g npm@10.3.0 to update! npm notice [root@vp vitepress-starter]# # 安装vitepress依赖,以下方式都可以,目的是安装vitepress依赖 npm add -D vitepress pnpm add -D vitepress yarn add -D vitepress bun add -D vitepress [root@vp vp]# pnpm add -D vitepress Packages: +73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Progress: resolved 108, reused 0, downloaded 73, added 73, done node_modules/.pnpm/vue-demi@0.14.6_vue@3.4.13/node_modules/vue-demi: Running postinstall script, done in 966ms node_modules/.pnpm/esbuild@0.19.11/node_modules/esbuild: Running postinstall script, done in 516ms devDependencies: + vitepress 1.0.0-rc.36 Done in 13.7s [root@vp vp]# pwd /vp [root@vp vp]# ll total 40 drwxr-xr-x. 4 root root 69 Jan 15 11:45 node_modules -rw-r--r--. 1 root root 58 Jan 15 11:45 package.json -rw-r--r--. 1 root root 34367 Jan 15 11:45 pnpm-lock.yaml [root@vp vp]# # 初始化当前目录 # 如果使用pnpm初始化，则：回答以下问题 pnpm dlx vitepress init pnpm vitepress init [root@vp vp]# pnpm vitepress init ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # 手动指定文档根目录 # 如果正在构建一个独立的 VitePress 站点，可以在当前目录 (`./`) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 `./docs`) 中，以便它与项目的其余部分分开。 ◇ Site title: │ My Awesome Project │ ◇ Site description: │ A VitePress Site │ ◇ Theme: │ Default Theme │ ◇ Use TypeScript for config and theme files? │ Yes │ ◇ Add VitePress npm scripts to package.json? │ Yes │ └ Done! Now run pnpm run docs:dev and start writing. # 假设选择在 `./docs` 中搭建 VitePress 项目，生成的文件结构应该是这样的： [root@vp vp]# pwd /vp [root@vp vp]# tree -a ./docs/ . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ ├─ api-examples.md │ ├─ markdown-examples.md │ └─ index.md └─ package.json [root@vp vp]# # docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。默认情况下，VitePress 将其开发服务器缓存存储在
.vitepress/cache中，并将生产构建输出存储在.vitepress/dist中。如果使用 Git，应该将它们添加到.gitignore文件中。也可以手动配置这些位置。步骤3：启动和运行
shyarn docs:dev # or npm run docs:dev vitepress v1.0.0-rc.36 ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose ➜ press h to show help Shortcuts press r to restart the server press u to show server url press o to open in browser press c to clear console press q to quit # 默认仅在127.0.0.1上发布 [root@vp ~]# netstat -tunlp | grep :5173 tcp 0 0 127.0.0.1:5173 0.0.0.0:* LISTEN 9599/node [root@vp ~]# # 在所有接口上发布 [root@vp vitepress-starter]# yarn docs:dev --host 0.0.0.0 vitepress v1.0.0-rc.36 ➜ Local: http://localhost:5173/ ➜ Network: http://10.10.10.39:5173/ ➜ press h to show help
测试案例-使用yarn
步骤 1: 创建并进入一个目录
sh[root@vp /]# mkdir /web [root@vp /]# mkdir /vp [root@vp /]# cd /vp/ [root@vp vp]#步骤2: 安装npm并配置npm源
sh# 安装npm dnf install -y npm root@vp vp]# npm -v 8.19.4 # 设置npm源 npm config set registry https://registry.npmmirror.com步骤3: 安装yarn并配置yarn源
sh[root@vp vp]# npm install --global yarn added 1 package in 4s npm notice npm notice New major version of npm available! 8.19.4 -> 10.3.0 npm notice Changelog: https://github.com/npm/cli/releases/tag/v10.3.0 npm notice Run npm install -g npm@10.3.0 to update! npm notice [root@vp vp]# yarn -v 1.22.21 [root@vp vp]# # yarn并不共享npm的源，因此还需要手动改为国内 [root@vp vp]# yarn config get registry https://registry.yarnpkg.com [root@vp vp]# yarn config set registry https://registry.npmmirror.com yarn config v1.22.21 success Set "registry" to "https://registry.npmmirror.com". Done in 0.14s. [root@vp vp]# yarn config get registry https://registry.npmmirror.com [root@vp vp]#步骤4: 安装vitepress依赖
sh# 在此之前需要先升级node版本，否则在执行yarn add --dev vitepress时会遇到以下错误： [root@vp vp]# yarn add --dev vitepress yarn add v1.22.21 info No lockfile found. [1/4] Resolving packages... [2/4] Fetching packages... error @vitejs/plugin-vue@5.0.3: The engine "node" is incompatible with this module. Expected version "^18.0.0 || >=20.0.0". Got "16.20.2" error Found incompatible module. info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.更换node版本参见Linux更换node以及npm版本
注意：安装依赖时应该位于
/vp目录下shroot@vp vp]# yarn add -D vitepress yarn add v1.22.21 info No lockfile found. (node:276) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... warning "vitepress > @docsearch/js > @docsearch/react > @algolia/autocomplete-preset-algolia@1.9.3" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6". warning "vitepress > @docsearch/js > @docsearch/react > @algolia/autocomplete-core > @algolia/autocomplete-shared@1.9.3" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6". warning "vitepress > @docsearch/js > @docsearch/react > @algolia/autocomplete-core > @algolia/autocomplete-plugin-algolia-insights@1.9.3" has unmet peer dependency "search-insights@>= 1 < 3". [4/4] Building fresh packages... success Saved lockfile. success Saved 52 new dependencies. info Direct dependencies └─ vitepress@1.0.0-rc.36 info All dependencies ├─ @algolia/autocomplete-core@1.9.3 ├─ @algolia/autocomplete-plugin-algolia-insights@1.9.3 ├─ @algolia/autocomplete-preset-algolia@1.9.3 ├─ @algolia/cache-browser-local-storage@4.22.1 ├─ @algolia/cache-in-memory@4.22.1 ├─ @algolia/client-account@4.22.1 ├─ @algolia/client-analytics@4.22.1 ├─ @algolia/client-personalization@4.22.1 ├─ @algolia/logger-console@4.22.1 ├─ @algolia/requester-browser-xhr@4.22.1 ├─ @algolia/requester-node-http@4.22.1 ├─ @docsearch/css@3.5.2 ├─ @docsearch/js@3.5.2 ├─ @docsearch/react@3.5.2 ├─ @esbuild/linux-x64@0.19.11 ├─ @jridgewell/sourcemap-codec@1.4.15 ├─ @rollup/rollup-linux-x64-gnu@4.9.5 ├─ @rollup/rollup-linux-x64-musl@4.9.5 ├─ @types/estree@1.0.5 ├─ @types/linkify-it@3.0.5 ├─ @types/markdown-it@13.0.7 ├─ @types/mdurl@1.0.5 ├─ @types/web-bluetooth@0.0.20 ├─ @vitejs/plugin-vue@5.0.3 ├─ @vue/compiler-sfc@3.4.13 ├─ @vue/devtools-api@6.5.1 ├─ @vue/reactivity@3.4.13 ├─ @vue/runtime-core@3.4.13 ├─ @vue/runtime-dom@3.4.13 ├─ @vue/server-renderer@3.4.13 ├─ @vueuse/core@10.7.2 ├─ @vueuse/integrations@10.7.2 ├─ @vueuse/metadata@10.7.2 ├─ algoliasearch@4.22.1 ├─ csstype@3.1.3 ├─ entities@4.5.0 ├─ esbuild@0.19.11 ├─ focus-trap@7.5.4 ├─ magic-string@0.30.5 ├─ mark.js@8.11.1 ├─ minisearch@6.3.0 ├─ nanoid@3.3.7 ├─ picocolors@1.0.0 ├─ preact@10.19.3 ├─ rollup@4.9.5 ├─ shikiji-core@0.9.19 ├─ shikiji-transformers@0.9.19 ├─ shikiji@0.9.19 ├─ tabbable@6.2.0 ├─ vite@5.0.11 ├─ vitepress@1.0.0-rc.36 └─ vue@3.4.13 Done in 50.50s. [root@vp vp]#步骤5: 初始化当前目录
sh# 使用yarn初始化 [root@vp vp]# yarn init yarn init v1.22.21 warning package.json: No license field question name (vp): question version (1.0.0): question description: docs question entry point (index.js): question repository url: question author: question license (MIT): question private: success Saved package.json Done in 60.62s. [root@vp vp]# pwd /vp [root@vp vp]# ll -a total 44 drwxr-xr-x. 3 root root 63 Jan 15 12:45 . drwxr-xr-x. 1 root root 83 Jan 15 12:40 .. drwxr-xr-x. 36 root root 4096 Jan 15 12:45 node_modules -rw-r--r--. 1 root root 168 Jan 15 12:47 package.json -rw-r--r--. 1 root root 35840 Jan 15 12:45 yarn.lock [root@vp vp]# cat package.json { "devDependencies": { "vitepress": "^1.0.0-rc.36" }, "name": "vp", "version": "1.0.0", "description": "docs", "main": "index.js", "license": "MIT" } [root@vp vp]#步骤6: 创建首页
sh[root@vp vp]# mkdir docs && echo '# Hello VitePress' > docs/index.md [root@vp vp]#步骤7: 在
package.json.添加script部分sh# 在 package.json 中增加打包以及运行的指令。 [root@vp vp]# cat package.json { "devDependencies": { "vitepress": "^1.0.0-rc.36" }, "name": "vp", "version": "1.0.0", "description": "docs", "main": "index.js", "license": "MIT", "scripts": { "docs:dev": "vitepress dev docs", # 本地运行测试 "docs:build": "vitepress build docs", # 项目打包：最终结果会在 .vitepress/dist 中 "docs:serve": "vitepress serve docs" # 预览打包后的效果，此命令只有 build 成功后才会执行成功。 } } [root@vp vp]# # 添加"type": "module" # 如果不添加module，则config.js中的export指令可能无法使用步骤8: 启动
shyarn docs:dev # or npm run docs:dev vitepress v1.0.0-rc.36 ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose ➜ press h to show help Shortcuts press r to restart the server press u to show server url press o to open in browser press c to clear console press q to quit # 默认仅在127.0.0.1上发布 [root@vp ~]# netstat -tunlp | grep :5173 tcp 0 0 127.0.0.1:5173 0.0.0.0:* LISTEN 9599/node [root@vp ~]# # 在所有接口上发布 [root@vp vitepress-starter]# yarn docs:dev --host 0.0.0.0 vitepress v1.0.0-rc.36 ➜ Local: http://localhost:5173/ ➜ Network: http://10.10.10.39:5173/ ➜ press h to show help其他:
sh# 启动后自动生成.vitepress目录 [root@vp docs]# tree -a /vp/docs/ /vp/docs/ ├── .vitepress │ └── cache │ └── deps │ ├── @theme_index.js │ ├── @theme_index.js.map │ ├── _metadata.json │ ├── chunk-HL7EECYQ.js │ ├── chunk-HL7EECYQ.js.map │ ├── chunk-OECM7FRU.js │ ├── chunk-OECM7FRU.js.map │ ├── package.json │ ├── vitepress___@vue_devtools-api.js │ ├── vitepress___@vue_devtools-api.js.map │ ├── vitepress___@vueuse_core.js │ ├── vitepress___@vueuse_core.js.map │ ├── vue.js │ └── vue.js.map └── index.md 3 directories, 15 files [root@vp docs]#
文件目录结构
如果你正在构建一个独立的 VitePress 站点，你可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。
假设你选择在 ./docs 中搭建 VitePress 项目，使用pnpm dlx vitepress init进行初始化，则生成的文件结构应该是这样的：
bash
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsondocs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。
默认情况下，VitePress 将其开发服务器缓存存储在
.vitepress/cache中，并将生产构建输出存储在.vitepress/dist中。如果使用 Git，应该将它们添加到.gitignore文件中。也可以手动配置这些位置。
核心配置文件
<root>/.vitepress/config.[ext]
配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：
bash
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ └─ index.md
└─ package.json一个 VuePress 站点必要的配置文件是 .vuepress/config.js，它应当导出一个 JavaScript 对象：
js
module.exports = {
title: 'Hello VitePress',
description: 'Just playing around.'
}
// 两种语法：推荐下面这种语法
// .vitepress/config.js
export default {
// site-level options
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// theme-level options
}
}还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的完整详细信息，请参见配置参考。
源文件
.vitepress 目录之外的 Markdown 文件被视为源文件。
VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。
VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些将在路由指南中进行介绍。
启动和运行
应该将以下 npm 脚本注入到 package.json 中：
如果使用pnpm初始化，则会自动添加
json
{
...
"scripts": {
"docs:dev": "vitepress dev docs", //开发服务器，用于本地运行测试
"docs:build": "vitepress build docs", //构建，项目打包：最终结果会在 .vitepress/dist 中
"docs:preview": "vitepress preview docs" //预览打包后的效果，此命令只有 build 成功后才会执行成功。
},
...
}docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：
sh
npm run docs:devsh
pnpm run docs:devsh
yarn [run] docs:devsh
bun run docs:dev监听所有地址和指定端口
bash
# 默认仅在127.0.0.1上发布
[root@vp ~]# netstat -tunlp | grep :5173
tcp 0 0 127.0.0.1:5173 0.0.0.0:* LISTEN 9599/node
[root@vp ~]#
# 在所有接口上发布
[root@vp vitepress-starter]# yarn docs:dev --host 0.0.0.0 --port 80
vitepress v1.0.0-rc.36
➜ Local: http://localhost:80/
➜ Network: http://10.10.10.39:80/
➜ press h to show help除了 npm 脚本，还可以直接调用 VitePress：
sh
npx vitepress dev docssh
pnpm exec vitepress dev docssh
bunx vitepress dev docs开发服务应该会运行在 http://localhost:5173上。在浏览器中访问 URL 以查看新站点的运行情况吧！