前端- Vue3企业管理后台项目实战总结 - 个人文章
侧边栏壁纸
博主昵称
七叶

  • 累计撰写 41 篇文章
  • 累计收到 1 条评论
前端笔记

前端- Vue3企业管理后台项目实战总结 - 个人文章

七叶
七叶
2026-04-29 / 0 阅读 / 正在检测是否收录...

十、文档生成（VitePress）

核心目标：搭建组件库的文档站，包含组件示例、API说明、快速上手等内容，方便开发者使用。

步骤1：安装VitePress依赖

pnpm add -D vitepress@latest markdown-it-container@latest
1.
依赖作用解释：

依赖名

作用

vitepress

Vue官方文档工具（基于Vite，支持Markdown+Vue组件，生成静态文档站）

markdown-it-container

Markdown扩展插件（用于自定义容器，比如示例代码块、提示框等）

步骤2：初始化VitePress目录结构

在项目根目录创建docs目录：结构如下：

docs/
├── .vitepress/ # VitePress配置目录
│ ├── config.ts # 核心配置文件
│ ├── theme/ # 自定义主题（可选）
│ │ └── index.ts # 主题入口
├── components/ # 组件文档目录
│ ├── button.md # Button组件文档
├── guide/ # 指南文档目录
│ ├── quick-start.md # 快速上手
├── index.md # 文档首页
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
步骤3：配置VitePress（docs/.vitepress/config.ts）

import { defineConfig } from 'vitepress';
import MarkdownIt from 'markdown-it';
import container from 'markdown-it-container';
import { resolve } from 'path'; // 必须引入 path 模块

const md = MarkdownIt({

html: true,     // 允许 Markdown 中嵌入 HTML 标签
linkify: true,  // 自动识别链接
typographer: true,     // 启用排版优化

});

// 注册 demo-block 容器（格式：:::demo-block 内容 :::）
md.use(container, 'demo-block', {

// 自定义容器的渲染逻辑（后续可结合主题组件完善）
render: (tokens: any, idx: number) => {
    const token = tokens[idx];
    // 开始标签：::: demo-block
    if (token.nesting === 1) {
        return '<demo-block>\n';
    }
    // 结束标签
    return '</demo-block>\n';
},

});
// 可选：注册tip提示框容器（::: tip内容 :::）
md.use(container, 'tip', {

render: (tokens: any, idx: number) => {
    const token = tokens[idx];
    if (token.nesting === 1) {
        return '<div class="tip-contaienr">\n';
    }
    return '</div>\n';
},

});

//VitePress 主配置
export default defineConfig({

// ============================ 站点基础配置 =============================
title: 'Vue3组件库',        // 文档站的标题（会显示在浏览器标签栏）
titleTemplate: ':title - 开箱即用的vue3组件库',     // 标题模板（可选，格式：[页面标题] - [站点副标题]）
description: '基于Vue3+TS+Vite构建的后台管理系统公共组件库，提供丰富的UI组件和完整的类型支持',      //站点描述（SEO用）
base: '/vue3-component-library/',   // 部署基础路径（重要！）
lang: 'zh-CN',      // 站点语言（默认zh-US，推荐设为 zh-CN）
cleanUrls: true,    // 启用干净的 URL（去掉 .html 后缀，如 /guide/quick-start 而非 /guide/quick-start.html）

// ============================ 主题配置（内置主题） ======================
themeConfig: {
    // 站点logo
    logo: '/vite.svg',
    // 站点导航栏右侧的深色/浅色模式切换
    darkModeSwitchLabel: '主题',
    // 导航栏右侧的与语言切换（若需要多语言）
    langMenuLabel: '语言',

    // 顶部导航栏（Nav）配置
    nav: [
        {
            text: '指南',       // 导航栏文字
            link: '/guide/quick-start',     // 点击跳转的路径（对应 docs/guide/quick-start.md）
            // 可选：下拉菜单（若指南有多个子页面）
            // items: [
            //    { text: '快速上手', link: '/guide/quick-start' },
            //    { text: '配置说明', link: '/guide/config' },
            // ],
        }, 
        {
            text: '组件',
            link: '/components/button',
            // 可选：下拉菜单（组件较多时）
            // items: [
            //   { text: 'Button 按钮', link: '/components/button' },
            //   { text: 'Input 输入框', link: '/components/input' }
            // ]
        },
        { 
            text: 'GitLab', // 可选：链接到 GitHub 仓库
            link: 'https://jihulab.com/chj_158-group/vue3-component-library.git',
            target: '_blank' // 新标签页打开
        }
    ],

    // 侧边栏（Sidebar）配置：按路径分组（不同目录显示不同侧边栏）
    sidebar: {
        // 指南目录（/guide/ 开头的路径）的侧边栏
        '/guide/': [
            {
                text: '指南',       // 侧边栏组标题（可选，不写则无分组）
                collapsed: false,   // 是否默认折叠（false 为展开）
                items: [
                    { text: '快速上手', link: '/guide/quick-start' },   // 对应 quick-start.md
                    // 可选：添加更多指南页面
                    // { text: '按需引入', link: '/guide/按需引入' },
                    // { text: '主题定制', link: '/guide/主题定制' }
                ],
            },
        ],
        // 组件目录（/components/ 开头的路径）的侧边栏
        '/components/': [
            {
                text: '基础组件',
                collapsed: false,
                items: [
                    { text: 'Button 组件', link: '/components/button' },
                    // 可选：添加更多组件
                    { text: '智能体 组件', link: '/components/agent' },
                    // { text: 'Card 卡片', link: '/components/card' }
                ]
            }
        ]
    }
},

// ============================ Vite 配置（继承扩展Vite配置）===============
vite: {
    // 解析配置：路径别名（让文档中能直接引用 src 目录的组件）
    resolve: {
        alias: {
            // 把 @ 指向项目根目录的 src 目录（关键！这样在md中可以 import Button from '@/components/Button/Button.vue'）
            '@': resolve(__dirname, '../../src'),
            // 可选：添加其他别名
            // 'vue3-component-library': '/src'
        }
    },
     // 可选：开发服务器配置
    server: {
        port: 5174, // 自定义文档开发服务器端口（默认 5173，若被占用可修改）
        open: true // 启动时自动打开浏览器
    },
    // 可选：构建配置
    build: {
        chunkSizeWarningLimit: 1000 // 增大 chunk 大小警告阈值（默认 500kb）
    }
},

 // ===================== Markdown 配置 =====================
markdown: {
    // 传递自定义的 Markdown 解析器（我们之前注册了 demo-block 容器）
    renderer: md,
    // 可选：启用代码行号
    lineNumbers: true,
    // 可选：配置 Markdown 插件
    config: (md) => {
    // 可在这里注册更多 Markdown 插件（如 markdown-it-emoji 表情插件）
        // md.use(require('markdown-it-emoji'));
    }
}

})
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
146.
147.
上图是我的初版配置项 ，可根据自己的项目进行更改。

步骤4：编写文档内容

（1）首页（docs/index.md）

首页布局配置（固定格式）

layout: home

页面标题（会覆盖站点标题）

title: Vue3组件库

页面描述（会覆盖站点描述）

description: 基于Vue3+TS+Vite构建的后台管理系统公共组件库

<div class="hero-container">
    <h1>Vue3组件库</h1>
    <p class="hero-subtitle">基于Vue3+TS+Vite构建，开箱即用的后台管理系统组件库</p>
    <div class="hero-demo">
        <VButton type="primary" size="large">立即使用</VButton>
        <VButton type="default" size="large" style="margin-left: 1rem;">查看文档</VButton>
    </div>
    <div class="hero-actions">
        <a href="guide/quick-start" class="vp-button vp-button__brand vp-button--lg">
            快速上手
        </a>
        <a href="components/button" class="vp-button vp-button--lg">
            组件列表
        </a>
    </div>
</div>
<div class="features-container">
    <div class="feature-item">
        <h3>类型安全</h3>
        <p>基于TypeScript开发，完善的类型定义，开发时自动提示，减少错误</p>
    </div>
    <div class="feature-item">
        <h3>按需引入</h3>
        <p>支持Tree Shaking，按需引入组件和样式，显著减小项目体积</p>
    </div>
    <div class="feature-item">
        <h3>样式可定制</h3>
        <p>基于Sass的样式变量，支持全局主题定制和单个组件样式覆盖</p>
    </div>
    <div class="feature-item">
        <h3>响应式设计</h3>
        <p>适配桌面、平板、手机等多种设备，支持响应式布局</p>
    </div>
    <div class="feature-item">
        <h3>丰富的组件</h3>
        <p>覆盖后台管理系统的常用组件，如按钮、输入框、表格、弹窗等</p>
    </div>
    <div class="feature-item">
        <h3>易扩展</h3>
        <p>组件设计遵循高内聚低耦合原则，支持二次开发和扩展</p>
    </div>
</div>


1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
（2）快速上手（docs/guide/quick-start.md）

快速上手

本文将指导你如何快速在项目中使用 Vue3组件库。

前置条件

在使用 Vue3组件库 之前，请确保你的项目满足以下条件：

  • Vue 版本 ≥ 3.2.0（推荐使用 Vue 3.3+）
  • TypeScript 版本 ≥ 4.5.0（可选，若使用 TS）
  • Vite / Webpack 等构建工具（推荐 Vite）

安装

使用 pnpm 安装（推荐）

pnpm add @bruce_cao/vue3-component-library

使用 npm 安装

npm install @bruce_cao/vue3-component-library --save

使用 yarn 安装

yarn add @bruce_cao/vue3-component-library

引入方式

方式一：全局引入（推荐用于小型项目）

全局引入会将所有组件注册为全局组件，无需逐个引入，方便快捷。

步骤1：在 main.ts 中引入
// src/main.ts（Vue3 项目入口文件）
import { createApp } from 'vue';
import App from './App.vue';
// 引入组件库
import Vue3ComponentLibrary from '@bruce_cao/vue3-component-library';
// 引入组件库样式（全局样式）
import '@bruce_cao/vue3-component-library/dist/vue3-component-library.css';

const app = createApp(App);
// 全局注册组件库
app.use(Vue3ComponentLibrary);
app.mount('#app');
步骤2：在组件中使用
<template>
   <VButton type="primary">主要按钮</VButton>
   <VButton type="default">默认按钮</VButton>
</template>

方式二：按需引入（推荐用于大型项目）

按需引入只会引入使用的组件和样式，减少项目体积，推荐在大型项目中使用。

步骤1：直接引入组件和样式
<template>
  <VButton type="primary">主要按钮</VButton>
</template>

<script setup lang="ts">
// 引入 Button 组件
import { Button as VButton } from '@bruce_cao/vue3-component-library';
// 引入 Button 组件的样式
import '@bruce_cao/vue3-component-library/dist/button/vue3-component-library.css';
</script>
步骤2：自动按需引入（可选，使用unplugin-vue-components）

为了简化按需引入的步骤，可以使用 unplugin-vue-components 插件实现自动引入组件和样式

安装插件
pnpm add -D unplugin-vue-components unplugin-auto-import
配置Vite
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import { Vue3ComponentLibraryResolver } from '@bruce_cao/vue3-component-library/resolver'; // 需组件库提供解析器

export default defineConfig({
  plugins: [
    vue(),
    Components({
      // 自动引入组件库的组件
      resolvers: [Vue3ComponentLibraryResolver()],
    }),
  ],
});

之后即可直接使用组件（无需手动引入）

<template>
    <VButton type="primary">主要按钮</VButton>
</template>

主题定制

Vue3组件库基于 Sass 提供了丰富的样式变量，你可以通过覆盖这些变量来定制主题。

步骤1：创建自定义样式文件
// src/styles/custom-theme.scss
// 覆盖组件库的默认变量
$primary-color: #1890ff;    // 主色调改为蚂蚁金服蓝
$button-border-radius: 4px;   // 按钮圆角改为4px 

// 引入组件库的样式文件
@import '@bruce_cao/vue3-component-library/dist/vue3-component-library.css';
步骤2：在 main.ts 中引入自定义样式
// src/main.ts
import { createApp } from 'vue';
import App from './App.vue';
import Vue3ComponentLibrary from 'vue3-component-library';
// 引入自定义样式（替换原有样式文件）
import './styles/custom-theme.scss';

const app = createApp(App);
app.use(Vue3ComponentLibrary);
app.mount('#app');

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
tips:以上代码都是我项目初期搭建时的基础配置项，此处只是做一个样例，可以根据自己的项目做相关调整。

步骤5：添加文档脚本（package.json）

 

{

"scripts": {
    "docs:dev": "vitepress dev docs",         // 启动文档开发服务器
    "docs:build": "vitepress build docs",     // 构建文档静态文件
    "docs:preview": "vitepress preview docs"  // 预览构建后的文档
}

}
1.
2.
3.
4.
5.
6.
7.
步骤6：运行 / 构建文档

pnpm docs:dev // 启动文档开发服务器
pnpm docs:build // 构建文档（输出到docs/.vitepress/dist）
pnpm docs:preview // 预览构建后的文档
1.
2.
3.
十一：发布到npm

核心目标：将组件库发布到npm仓库，支持其他项目安装使用。

步骤1：npm账号准备

             1.注册npm账号：访问 npm官网 完成注册。

             2.登录npm（终端执行）：

npm login
1.
         输入用户名、密码、邮箱（注意：若使用淘宝镜像，需要先切换回官方镜像：npm config set registry https://registry.npmjs.org/）。

步骤2：晚上package.json配置

确保package.json包含以下关键配置

{
"name": "vue3-component-library", // npm包名（需唯一，建议前缀+项目名）
"version": "0.0.1", // 版本号（遵循语义化版本：主版本.次版本.补丁）
"private": false, // 必须为false（私有包需付费）
"main": "./dist/vue3-component-library.umd.js", // UMD格式入口（兼容浏览器/Node）
"module": "./dist/vue3-component-library.es.js", // ES模块入口（现代打包工具）
"types": "./dist/index.d.ts", // 类型声明文件入口
"files": ["dist"], // 发布时包含的文件（仅dist目录）
"peerDependencies": { // 对等依赖（用户需自行安装Vue）

"vue": "^3.0.0"

},
"license": "MIT", // 开源协议（必填）
"repository": { // 仓库地址（可选）

"type": "git",
"url": "https://github.com/你的仓库/vue3-component-library.git"

},
"keywords": ["vue3", "component library", "ts", "vite"], // 关键词（便于搜索）
"author": "你的名字 <你的邮箱>" // 作者信息（可选）
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
步骤3：生成类型声明文件

若基础构建未生成d.ts文件，需安装vue-tsc并调整构建脚本：

pnpm add -D vue-tsc@latest
1.
修改package.json的build脚本：

{
"scripts": {

"build": "vue-tsc --declaration --emitDeclarationOnly && vite build"

}
}
1.
2.
3.
4.
5.
vue-tsc --declaration --emitDeclarationOnly：仅生成类型声明文件（输出到src目录，需手动移动到dist，或配置tsconfig.json的outDir）。

优化tsconfig.json的compilerOptions:

{
"compilerOptions": {

// 原有配置保留
"declaration": true, // 生成d.ts文件
"declarationDir": "./dist/types", // 类型文件输出目录
"emitDeclarationOnly": true // 仅生成类型文件

}
}
1.
2.
3.
4.
5.
6.
7.
8.
步骤4：打包组件库

pnpm build
1.
打包完成后需检查dist目录，确保包含：

vue3-component-library.es.js（ES模块）
vue3-component-library.umd.js（UMD模块）
index.d.ts（类型声明）
style.css（样式文件）
步骤5：发布到npm

npm publish
1.
发布注意事项：

1.版本号不能重复（发布前需要更新版本：npm version patch/minor/major）。

2.若包名已经被占用，需修改package.json的name字段。

3.发布后可在npm官网搜索包名，确认是否发布成功。

步骤6：发布后测试安装

在想要引入该组件库的vue3项目中安装测试：

pnpm add vue3-component-library
1.
在项目中引入使用：

登录后复制

暂无标签
版权属于： 七叶
本文链接： http://outt.cn/index.php/archives/3/