如何快乐地使用vite开发npm库（typescript），搭建·调试·发布·闭环式教程

本文示例源码：gitee、github、npm 地址，欢迎 start 哦。

本教程将介绍：

• 如何搭建一个 vite 项目，并配置为库模式，为 es 模块化、umd 打包出对应语法的两套 js 库文件。
• 用 typescript 开发库时，如何在 vite 中自动生成声明文件呢。
• 开发库时 package.json 中哪些属性必须设置。e.g：只发布哪些文件到 npm 上，以及不同导入方式，会返回哪个文件给人家。
• 关于软链接 npm link 相关的命令，让你在本地提前安装上要发布的库并使用。
• 也会介绍热更新式的调试模式，提升开发体验！
• 在 npm 设置了淘宝镜像的情况下。如何便捷登录和发布 npm 包到官方源。

整个流程中的一些坑也会在介绍中提示。

前置知识 - 关于库（包）名

任何库的库名都是对应 package.json 里的 name 属性值（与文件名，导出什么模块没关系），安装第三方依赖库时，也是通过它来找到该库，所以如果要发布到 npm 上，name 值必须是 npm 上没有发布过的。

npm info packagename 

既然库名和代码没任何关系，那 import xxx from 'packagename' 时，是怎么找到对应的模块所在的 js 文件的呢? 答案在 package.json 里，它的 main、module` 属性值保存了不同导入方式，指向哪个 js 文件的信息。文章后面也会介绍。

下面介绍中用到的 packagename 就是指代 package.json 里的 name 值。

搭建 vite 项目来打包库

1. 假设我们要开发一个叫 lite-move 的库，初始化项目文件夹时，文件夹目录名也应该和库名一致：

   
   mkdir lite-move && cd lite-move && mkdir src && npm init -y
   

2. 然后安装 vue、vite 为开发依赖，这里假设是开发 vue 生态的插件：

   
   npm i vue vite -D
   

3. 然后在项目 src 目录里创建个入口文件，例如 lite-move.ts，随便写点东西：

   
   console.log('hellow npm')
   

4. 创建vite.config.js，并配置为库模式，可到 vite 官网查看更多：

   import { resolve } from 'path'
   import { defineConfig } from 'vite'
   
   
   export default defineConfig({
     build: {
       lib: {
         entry: resolve(__dirname, './src/lite-move.ts'),
         name: 'liteMove',
         
         fileName: 'lite-move',
       },
       rollupOptions: {
         
         external: ['vue'],
         output: {
           
           globals: {
               liteMove: 'liteMove',
           },
         },
       },
     },
   })
   

5. 到这里，就可以用 vite 打包了：

   
   npx vite build
   

   执行以上命令后，构建结果会输出到 dist 目录，默认有两个 js 文件，它们只是使用的导出规范（语法）不同，具体代码功能是一样的。

   • lite-move.umd.js：umd 导出方式，兼容 amd commenjs 等导出的库实现。

   • lite-move.mjs：es 模块化导出方式的库实现。

     有了这俩文件，就可以覆盖目前主流的多种前端模块化环境了，在不同的环境，导入对应的 js 文件即可。

自动生成 dts 声明文件

配置好 vite.config.js 后，就可以构建了。但是如果是使用 ts 开发库，则需要配置自动生成 dts 声明文件（不想自己写），有两种方式。如果使用 js 开发，跳过这一步即可。

1. 方式一：自己安装 typescript 并配置tsconfig.js。

   首先，安装依赖并生成tsconfig.json：

   
   npm i typescript -D
   
   npx tsc --init
   

   然后，修改生成的 tsconfig.json，让 tsc 命令只生成声明文件，不转译 ts 文件：

   {
       "compilerOptions":{
           
           "declaration": true, 
           "declarationDir": "dist", 
           "emitDeclarationOnly": true, 
       }
   }
   

   最后，在执行 vite 构建命令时，同时执行一下 tsc 来生成声明文件：

   npx vite build && npx tsc
   

2. 方式二（推荐）：使用 vite 插件，执行 vite 命令时，会一并生成声明文件。如 vite-plugin-dts 插件。

   首先，安装 vite-plugin-dts 依赖：

   
   npm i vite-plugin-dts -D
   

   然后，在 vite 中引入该插件，并注册：

   该插件会默认先读取根目录 tsconfig.json（没有则使用默认的）的部分配置，但入口文件，输出目录会和 vite 保持一致。

   
   import dts from 'vite-plugin-dts'
   ​
   export default defineConfig({
     
     plugins: [dts()],
   })
   

   最后，直接执行 vite 构建命令，即可同时生成声明文件：

   npx vite build
   

   注：

   • 上面两种方式，生成的声明文件，是和 src 文件夹里的 ts 文件一一对应的，如src/my-lib.ts => dist/my-lib.d.ts。

   • vite 配置的库输出文件名：build.lib.filename、入口文件名、库名三者最好一致，这样声明文件名的头部名字和库名可以对上。否则可能出现声明文件不生效的问题。

   • 如果在入口文件里需要导入某个文件夹里的 index.ts，务必把路径写全，如：import xx from "tools/index"，如果把 index 文件名省略，自动生成 dts 的插件是无法正常找到 index 文件的。

配置 package.json 指定库信息

上面的步骤中，vite 的作用有两个：

一、为不同导出规范，打包出对应的 js 文件（模块），如 es 模块化和 umd。

二、生成对应的 dts 声明文件。

打包结果输出到 dist 目录后，还不能称为一个 npm 库，还缺少库的描述信息，如库名、版本、不同导入方式返回哪个文件等信息。这些信息都需要在 package.json 的对象里定义。

当一个业务项目中（通过 npm 下载）导入一个库时，是导入它提供的 es 模块化的文件还是 umd 的文件呢，这就需要读取 package.json 的 main 和 module 属性来决定。

如果有 dts 声明文件（上面步骤生成的，没有则不配置），还需要指定声明文件路径：

• typings：声明文件的路径。

另外还有三个与发布相关的属性：

• name：库名，在 npm 上必须唯一，否则无法发布，别人也是通过该库名来执行下载 npm install 的。
• files：指定哪些文件要发布到 npm 上，一般指定为构建输出目录，如 dist。另外，根目录的 package.json、readme.md 无需指定，发布时也会带上。
• version：指定当前库的版本。每次发布都要把版本提高一下，否则无法发布到 npm 上。

指定 files 的意义：像 vite.config.js 等开发用的配置文件是不需要发布的，人家下载你的库，结果把开发配置文件也下了，会浪费网络资源。

另外 package.json 中还可配置 author、description、repository、license 等属性，但不会像上面介绍的几个会影响使用，可以参考热门库是怎么写的，如 await-to-js。

package.json

   {
     "name": "lite-move", 
     "version": "0.0.2", 
     "main": "dist/lite-move.umd.js", 
     "module": "dist/lite-move.mjs", 
     "typings": "dist/lite-move.d.ts", 
     "files": [
       "dist" 
     ]
   }
   

发布前调试

正在本地开发的库，在还没发布到 npm 之前，如何安装到真实的项目环境中调试呢？

可以给正在开发的库创建一个软链接，并把软链接放到你全局的 node_modules 目录中。相当于把它变成一个全局依赖。这个过程可以使用 npm link 来实现。

然后你本地的任意项目，都可以通过 npm link packagename 来安装该库。例如有一个 demo 项目，安装了你开发中的库后，demo 项目就可以实时访问并同步开发中的库的更改了，无需重复创建软链接和重新安装。

详细步骤：

首先，为已经构建好的库（已经构建好了产物、package.json 也配置了），在你的全局 node_modules 目录中生成一个软链接：

1. 在库目录下，执行：

   
   npm link
   
   
   npm unlink
   
   
   npm unlink packagename -g
   

2. 查看全局依赖目录下都安装了哪些依赖，来判断是否在全局成功创建、删除全局软连接：

   
   npm ls -g
   
   npm ls -g --depth 0
   
   
   npm ls packagename -g
   

然后，在本地的 demo 项目中，“下载”该库。

1. demo 项目，安装该开发中的库：

   
   npm link packagename
   
   
   
   npm unlink packagename
   

2. 查看 demo 项目中，是否成功安装该库：

   npm ls packagename : 可以查看依赖在项目中的被依赖关系及对应的版本。

   npm ls packagename
   

构建热更新

demo 项目通过软链接安装该库后，每当库项目打包好，都可以实时同步更改，无需重复卸载安装该库。我们要做到就是，改一次库的代码就执行一下构建命令，demo 项目也会同步最新的库文件。但每次都要手动构建会很麻烦。

可以在执行打包时，监听文件的变化，当文件变化后，立马构建，解放双手：

npx vite build --watch

注意：只能和自动生成 dts 的第二种方式搭配使用，因为频繁构建会把 tsc 生成的声明文件删除

发布到 npm 上

通过以上步骤构建好了产物、dts 声明文件，并把库信息更新到了 package.json 里后，测试也没问题了，就可以发布到 npm 上啦！

这里假设配置了淘宝镜像源，所以每句命令都指定访问目标为 npm 官方源。否则会报错。如果是使用 npm 官方源，直接使用 npm login 等命令即可。

首先，库项目目录下，执行登录命令，然后根据提示输入账号密码即可：

npm login --registry https://registry.npmjs.org

登录成功后，执行发布命令：

npm publish --registry https://registry.npmjs.org


npm unpublish --force --registry https://registry.npmjs.org

为了方便，可以把这些命令配置到 package.json 的 scripts 中。

注意执行 publish 的命令的属性名，不能是 publish，因为执行 npm run publish 会执行两次发布

package.json

 "scripts": {
    "build": "vite build",
    "build:watch": "vite build --watch",
    "pushnpm": "npm publish --registry https://registry.npmjs.org"
  },

第一次发版、后续的版本更新都通过以下命令发布即可，发布成功后会有邮件提示的。

npm run pushnpm

最后，不要忘了给你的库添加一个 readme.md 的文件，向大家介绍你的库怎么用，用你的库会收获哪些快乐等。