本篇文章为《前端组件库的开发与维护》系列的第一篇文章。本文案例在线文档：calendar.hxkj.vip。GitHub 仓库：github.com/TangSY/vue3…。

一、简介

本专栏将从以下九个维度，以本人开发的日历组件库为例，全链路讲解如何高效且规范的开发一个组件库、维护一个组件库。

1. 基础框架搭建
2. 核心逻辑实现
3. 主题换肤实现
4. 覆盖单元测试
5. 代码提交规范
6. 搭建文档网站
7. 自动生成 changelog
8. 自动集成/部署文档网站
9. 自动 npm 发包

希望通过本系列文章，你可以有所收获。

文档效果图

暗黑模式

代码示例、组件预览

二、技术选型

考虑到由于是做开源项目，并且出于学习的目的，所选用的技术会倾向于主流。Thus，选用了以下几个：

• TypeScript
• Vite 3
• Vue 3
• Vant-cli
• Jest
• Less

三、框架搭建

vant-cli 的使用

使用 vant-cli 提供的脚手架一键生成项目骨架

yarn create vant-cli-app

输入项目名称：

vue 版本选 Vue 3：

css 预处理器选 Less：

上述步骤完成之后，将会得到如下目录结构：

接下来简单介绍一下这个目录结构及其用途

源代码目录

基于 Vant CLI 搭建的组件库的基本目录结构如下所示：

hxkj-demo
├─ src                # 组件源代码
│   ├─ button        # button 组件源代码
│   └─ dialog        # dialog 组件源代码
│
├─ docs               # 静态文档目录
│   ├─ home.md       # 文档首页
│   ├─ quickstart.md # 快速上手引导
│   └─ changelog.md  # 更新日志
│
├─ vant.config.mjs    # Vant CLI 配置文件
├─ package.json
└─ README.md

单个组件的目录如下：

button
├─ demo             # 示例目录
│   └─ index.vue   # 组件示例
├─ index.vue        # 组件源码
└─ README.md        # 组件文档

使用 .vue 文件编写组件时，编译后会生成对应的 JS 和 CSS 文件，且 JS 文件中会自动引入 CSS 文件。

如果需要将 JS 和 CSS 解耦，实现主题定制等功能，在编写代码时就要使用独立的 JS 和 CSS 文件，如下所示：

button
├─ demo             # 组件示例
│   └─ index.vue   # 组件示例入口
├─ index.js         # 组件入口
├─ index.less       # 组件样式，可以为 less 或 scss
└─ README.md        # 组件文档

采用这种目录结构时，组件的使用者需要分别引入 JS 和 CSS 文件。

通过引入样式源文件（less 或 scss）并修改样式变量，可以实现主题定制功能。

构建结果目录

运行 build 命令会在 es 和 lib 目录下生成可用于生产环境的组件代码，结构如下：

project
├─ es                   # es 目录下的代码遵循 esmodule 规范
│   ├─ button          # button 组件编译后的代码目录
│   ├─ dialog          # dialog 组件编译后的代码目录
│   └─ index.js        # 引入所有组件的入口 (ESModule)
│
└─ lib                  # lib 目录下的代码遵循 commonjs 规范
    ├─ button           # button 组件编译后的代码目录
    ├─ dialog           # dialog 组件编译后的代码目录
    ├─ index.js         # 引入所有组件的入口
    ├─ index.less       # 所有组件未编译的样式入口
    ├─ index.css        # 打包后的组件样式，用于 CDN 引入
    ├─ [name].js        # 打包后的组件脚本，UMD 格式
    ├─ [name].es.js     # 打包后的组件脚本，ESModule 格式
    ├─ [name].min.js    # 打包和压缩后的组件脚本，UMD 格式
    └─ [name].es.min.js # 打包和压缩后的组件脚本，ESModule 格式

单个组件编译后的目录如下：

button
├─ index.js         # 组件编译后的 JS 文件
├─ index.css        # 组件编译后的 CSS 文件
├─ index.less       # 组件编译前的 CSS 文件，可以为 less 或 scss
└─ style            # 按需引入样式的入口
    ├─ index.js     # 按需引入编译后的样式
    └─ less.js      # 按需引入未编译的样式，可用于主题定制

类型声明

当组件库使用 TS 编写，且根目录下存在 tsconfig.declaration.json 文件，Vant CLI 会自动生成 .d.ts 类型声明文件。

tsconfig.declaration.json 的参考格式如下：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationDir": ".",
    "emitDeclarationOnly": true
  },
  "include": ["es/**/*", "lib/**/*"],
  "exclude": ["node_modules", "**/test/**/*", "**/demo/**/*"]
}

成功生成类型声明后，在 package.json 中添加类型入口声明：

{
  "typings": "lib/index.d.ts"
}

总结

到此，组件库搭建的第一步就算完成了，从下篇开始就进入正题了。

对此系列感兴趣的，不妨一键三连（点赞 + 关注 + 收藏），方便跟进后续文章。

欢迎在评论区留下大家宝贵的建议！

---

作者：HashTang

个人空间：hxkj.vip

GitHub 主页：github.com/TangSY