本地新建js公用库组件并打包发布到npm仓库详细说明

张谨为 發表於 2025-3-7 08:59:00

本地新建js公用库组件并打包发布到npm仓库详细说明

<blockquote>
有时候，我们想在本地开发一个公用js函数组件库，并上传到npm仓库供开发者使用，本文就详细介绍了从新建本地项目到发布至npm仓库的整过过程，供大家学习！
</blockquote>
<h1 id="1注册账号">1、注册账号</h1>
首先我们去npm官网注册一个账号，注册成功后请牢记账号和密码。
需要注意的是，现在npm登录好像启用了双因素认证机制，也就是登录的时候不仅需要密码登录，还需要通过发送邮件随机字符进行登录验证，所以在注册账号的时候，切记要牢记当时注册填写的邮箱。
<hr>
<h1 id="2初始化项目">2、初始化项目</h1>
这里我们使用IDE（VS Code）进行开发本地js组件库。
<h2 id="21packagejson">2.1、package.json</h2>
使用如下命令初始化生成package.json：
<pre><code class="language-bash">npm init -y
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303141705686-1183462573.png" alt="image" loading="lazy">
<h2 id="22typescript依赖">2.2、TypeScript依赖</h2>
使用如下命令安装开发的TypeScript依赖：
<pre><code class="language-bash">npm install typescript --save-dev
</code></pre>
此时在package.json文件中就会生成如下开发所需要的依赖包：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142106102-374654130.png" alt="image" loading="lazy">
<h2 id="23tsconfigjson">2.3、tsconfig.json</h2>
使用如下命令可初始化生成tsconfig.json：
<pre><code class="language-bash">npx tsc --init --declaration --target ES6 --module ESNext --declarationDir ./dist --outDir ./dist
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142247876-2141473818.png" alt="image" loading="lazy">
tsconfig.json中主要配置说明如下：
<pre><code class="language-json">{
"compilerOptions": {
"target": "es6", // 编译目标版本
"module": "esnext", // 模块规范
"declaration": true, // 生成.d.ts类型声明文件
"declarationDir": "./dist", // 声明文件输出目录
"outDir": "./dist", // 编译输出目录
"strict": true // 严格类型检查
}
}
</code></pre>
<hr>
<h1 id="3新建项目文件和文件夹">3、新建项目文件和文件夹</h1>
在项目根目录下分别新建如下文件和文件夹：
<ul>
<li>
README.md：用于编写该项目的说明信息的Markdown文件；
</li>
<li>
CHANGELOG.md：用于记录版本变更信息的Markdown文件；
</li>
<li>
src文件夹：用于存放ts/js源码的文件夹；
<ul>
<li>
index.ts文件：项目的入口文件；
</li>
<li>
types文件夹：用于存放源码中用到的type类型文件；
</li>
<li>
utils文件夹：用于存放源码中具体的ts/js函数文件。
</li>
</ul>
</li>
<li>
test文件夹：用于测试的源码文件夹。
</li>
</ul>
目录文件和文件夹结果如下图所示：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142526606-1505121826.png" alt="image" loading="lazy">
<hr>
<h1 id="4编写js函数代码">4、编写js函数代码</h1>
<ul>
<li>
在<code>/src/types</code>目录下新建<code>user.ts</code>文件，然后编写如下代码：
<pre><code class="language-ts">/**
* 用户信息实体
*/
export type UserModel = {
/** 用户姓 */
FirstName?: string;

/** 用户名 */
LastName?: string;

/** 年龄 */
Age?: number;
};
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142659772-324945080.png" alt="image" loading="lazy">
</li>
<li>
在<code>/src/utils</code>目录下新建<code>user.ts</code>文件，然后编写如下代码：
<pre><code class="language-ts">import { UserModel } from "../types/user";

/**
* 默认用户信息
*/
export const defaultUser: UserModel = {
FirstName: "Zhang",
LastName: "San",
Age: 18,
};

/**
* 获取用户信息
* @returns 返回用户信息
*/
export const getUser = (): UserModel => {
return defaultUser;
};

/**
* 获取用户全名
* @param firstName 姓
* @param lastName 名
* @returns 返回用户全名
*/
export const getFullName = (firstName: string, lastName: string): string => {
return `${firstName} ${lastName}`;
};
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142751692-1422031566.png" alt="image" loading="lazy">
</li>
<li>
上述代码中，我们就定义好了一个用户信息实体和获取用户的工具函数。接下来我们修改<code>/src/index.ts</code>文件，代码如下：
<pre><code class="language-ts">/** 导出/types/user.ts中的所有type */
export * from "./types/user";

/** 导出/utils/user.ts中的所有属性或函数 */
export * from "./utils/user";
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303142847121-1819372936.png" alt="image" loading="lazy">
</li>
</ul>
到此，上述的ts/js代码就编写完成了。
需要注意的是：编写ts/js函数或属性的时候，需要将注释按照规范写清楚，以便在业务项目使用的时候自动出现提示信息，方便开发者在IDE中（鼠标悬停）查阅。
<hr>
<h1 id="5打包配置">5、打包配置</h1>
此处我们介绍一下<code>rollup</code>和<code>microbundle</code>组件进行打包，推荐使用<code>rollup</code>组件。
<h2 id="51rollup推荐">5.1、rollup（推荐）</h2>
<h3 id="511安装打包组件">5.1.1、安装打包组件</h3>
在项目根目录分别执行如下命令：
<pre><code class="language-bash">npm install --save-dev rollup @rollup/plugin-typescript typescript tslib

npm install @rollup/plugin-terser --save-dev
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303143605709-81422749.png" alt="image" loading="lazy">
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303143710308-1055103420.png" alt="image" loading="lazy">
<h3 id="512新建rollupconfigmjs">5.1.2、新建rollup.config.mjs</h3>
在项目根目录新建<code>rollup.config.mjs</code>文件，并在该文件中写入如下代码：
<pre><code class="language-js">import typescript from "@rollup/plugin-typescript";
import terser from "@rollup/plugin-terser";

export default {
input: "src/index.ts",
output: [
 // 未压缩的ES模块
 {
 file: "dist/index.esm.js",
 format: "es",
 sourcemap: true, // 可选：生成SourceMap
 },
 // 压缩后的ES模块
 {
 file: "dist/index.esm.min.js",
 format: "es",
 plugins: [
 // 仅针对此输出启用压缩
 terser({
 compress: { drop_console: true }, // 删除console语句
 format: { comments: false }, // 移除注释
 }),
 ],
 sourcemap: true,
 },
 // 未压缩的CommonJS模块
 {
 file: "dist/index.cjs.js",
 format: "cjs",
 sourcemap: true,
 },
 // 压缩后的CommonJS模块
 {
 file: "dist/index.cjs.min.js",
 format: "cjs",
 plugins: [
 terser({
 compress: { drop_console: true },
 format: { comments: false },
 }),
 ],
 sourcemap: true,
 },
],
plugins: [
 typescript({
 tsconfig: "./tsconfig.json",
 // exclude: ["**/*.test.ts"],
 }),
],
};
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303144151421-1808247260.png" alt="image" loading="lazy">
<h3 id="513修改packagejson">5.1.3、修改package.json</h3>
修改package.json文件，修改的主要配置如下：
<pre><code class="language-json">{
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts",
"scripts": {
 "build": "rollup -c rollup.config.mjs"
}
}
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202506/346453-20250624131358351-785566953.png" alt="image" loading="lazy">
<h3 id="514运行打包">5.1.4、运行打包</h3>
执行如下命令进行打包：
<pre><code class="language-bash">npm run build
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303144739461-1881722792.png" alt="image" loading="lazy">
如上图所示，我们发现多了一个<code>dist</code>文件夹，该文件夹就是打包编译的文件目录了，下面则是<code>dist</code>文件夹中部分文件的展示。
dist\index.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145141765-820701055.png" alt="image" loading="lazy">
dist\types\user.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145152939-531139614.png" alt="image" loading="lazy">
dist\utils\user.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145203201-377324870.png" alt="image" loading="lazy">
dist\index.cjs.js：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145025822-517545810.png" alt="image" loading="lazy">
dist\index.cjs.js.map：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145105032-385033106.png" alt="image" loading="lazy">
dist\index.cjs.min.js：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303145121615-876410390.png" alt="image" loading="lazy">
<h2 id="52microbundle">5.2、microbundle</h2>
<h3 id="521安装打包组件">5.2.1、安装打包组件</h3>
在项目根目录执行如下命令：
<pre><code class="language-bash">npm install microbundle --save-dev
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228224322310-2073871924.png" alt="microbundle" loading="lazy">
出现的警告信息可忽略。
此时在package.json文件中就会生成如下图所示开发所需要的依赖包：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228224435596-1192270378.png" alt="microbundle" loading="lazy">
<h3 id="522修改packagejson">5.2.2、修改package.json</h3>
修改package.json文件的配置如下：
<pre><code class="language-json">{
"type": "module",
"source": "./src/index.ts",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
 ".": {
 "require": "./dist/index.js",
 "import": "./dist/index.mjs"
 }
},
"scripts": {
 "build": "microbundle"
}
}
</code></pre>
配置说明：
<pre><code class="language-json">{
"main": "./dist/index.js", // CommonJS 入口（可选）
"module": "./dist/index.mjs", // ES Module 入口
"exports": {
".": {
"require": "./dist/index.js", // CommonJS
"import": "./dist/index.mjs"// ES Module
}
}
}
</code></pre>
修改后的package.json如下图所示：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228225328659-337631466.png" alt="package.json" loading="lazy">
<h3 id="523运行打包">5.2.3、运行打包</h3>
执行如下命令进行打包：
<pre><code class="language-bash">npm run build
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230232359-830479069.png" alt="build" loading="lazy">
如上图所示，我们发现多了一个<code>dist</code>文件夹，该文件夹就是打包编译的文件目录了，下面则是<code>dist</code>文件夹中部分文件的展示。
index.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230411058-717254112.png" alt="image" loading="lazy">
user.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230424204-170651593.png" alt="image" loading="lazy">
user.d.ts：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230429274-1612877100.png" alt="image" loading="lazy">
index.cjs：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230530877-1698676341.png" alt="image" loading="lazy">
<h1 id="6发布前的准备">6、发布前的准备</h1>
<h2 id="61npmignore">6.1、.npmignore</h2>
我们在项目根目录下新建<code>.npmignore</code>文件，用于配置发布忽略的文件或文件夹，具体内容如下：
<pre><code class="language-bash">test/
package-lock.json
*.log
*.tgz
src
node_modules
.prettierrc.json
*.test.ts
tsconfig.json
rollup.config.js
rollup.config.mjs
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202506/346453-20250624131536647-801166243.png" alt="image" loading="lazy">
<h2 id="62配置packagejson文件">6.2、配置package.json文件</h2>
接下来我们需要配置配置package.json文件，完整配置如下所示：
<ul>
<li>
rollup打包对应的配置：
<pre><code class="language-json">{
"name": "rapid-utils",
"version": "1.0.19",
"description": "前端公共用函数处理工具库，如：数字的处理、字符串的处理、数组的处理、日期的处理等。",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "rollup -c rollup.config.mjs"
},
"keywords": [
"rapid",
"utils",
"helpers"
],
"author": {
"name": "qubernet",
"email": "qubernet@163.com",
"url": "https://www.cnblogs.com/qubernet"
},
"license": "MIT",
"devDependencies": {
"@rollup/plugin-terser": "^0.4.4",
"@rollup/plugin-typescript": "^12.1.2",
"rollup": "^4.41.1",
"tslib": "^2.8.1",
"typescript": "^5.8.3"
},
"dependencies": {
"@types/lodash": "^4.17.17",
"lodash": "^4.17.21"
}
}
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202506/346453-20250624131718173-665029038.png" alt="image" loading="lazy">
</li>
<li>
microbundle打包对应的配置：
<pre><code class="language-json">{
"name": "rapid-test",
"version": "1.0.0",
"description": "常用的公用处理函数。",
"type": "module",
"source": "./src/index.ts",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"require": "./dist/index.js",
"import": "./dist/index.mjs"
}
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "microbundle"
},
"keywords": [
"utils",
"helpers"
],
"author": {
"name": "qubernet",
"email": "qubernet@163.com",
"url": "https://www.cnblogs.com/qubernet"
},
"license": "MIT",
"devDependencies": {
"microbundle": "^0.15.1",
"typescript": "^5.7.3"
}
}
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228230934573-1997810848.png" alt="package.json" loading="lazy">
</li>
</ul>
到此，发布到npm仓库前的准备工作就完成了。
<hr>
<h1 id="7发布到npm">7、发布到npm</h1>
<h2 id="71修改镜像源">7.1、修改镜像源</h2>
在发布前，我们先将npm的镜像源修改为官网地址。
以管理员身份运行CMD。
<ul>
<li>
查看npm当前的镜像源
<pre><code class="language-bash">npm config get registry
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228231146082-550387258.png" alt="image" loading="lazy">
</li>
<li>
修改npm镜像源为官网地址（只需要执行该行命令即可，下面的修改为淘宝镜像源为了演示切换效果）
<pre><code class="language-bash">npm config set registry https://registry.npmjs.org
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228231240935-2026001959.png" alt="image" loading="lazy">
</li>
<li>
修改npm镜像源为淘宝地址
<pre><code class="language-bash">npm config set registry https://registry.npmmirror.com
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228231340575-1152845698.png" alt="image" loading="lazy">
</li>
</ul>
<h2 id="72登录到npm">7.2、登录到npm</h2>
执行如下命令登录到npm（执行了如下命令后，会输出一个链接，打开这个链接，并登录即可授权）：
<pre><code class="language-bash">npm login
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303152123836-317659774.png" alt="image" loading="lazy">
账号密码登录：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228231918794-2118901365.png" alt="login" loading="lazy">
邮箱验证码登录（此步骤请到申请账号时填写的邮箱获取验证码）：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228232014950-838865414.png" alt="login" loading="lazy">
登录授权成功：
<img src="https://img2024.cnblogs.com/blog/346453/202502/346453-20250228232120499-1409545121.png" alt="login" loading="lazy">
VS Code终端显示登录成功：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303152230731-768696118.png" alt="image" loading="lazy">
<h2 id="73发布到npm仓库">7.3、发布到npm仓库</h2>
执行如下命令发布到npm仓库：
<pre><code class="language-bash">npm publish --access=public
</code></pre>
说明：
<ul>
<li>
上述命令中用到了--access=public，该参数只是初次发布的时候会使用到，后续升级直接使用npm publish即可；
</li>
<li>
如果出现“npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/rapid-test - Package name too similar to existing package rapidtest; try renaming your package to '@quberfer/rapid-test' and publishing with 'npm publish --access=public' instead”错误导致发布失败，说明发布的包名可能和npm仓库中的包名有相似的或已经存在了，这时候我们只需要将发布的包名修改一个稍微特别的就可以了，如我们将rapid-test修改为rapid-test-tools
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303152517029-56599530.png" alt="image" loading="lazy">
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303152842510-1001825146.png" alt="image" loading="lazy">
</li>
</ul>
此时，我们登录到npm官网去查看，就有我们刚才发布的包了，如下图所示：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303153021772-513182050.png" alt="image" loading="lazy">
<hr>
<h1 id="8更新发布">8、更新发布</h1>
当我们的项目做了修改后，则需要更新发布。
注意：更新发布前也需要将npm的镜像源修改为官网地址。
<h2 id="81打包项目">8.1、打包项目</h2>
执行如下命令打包项目：
<pre><code class="language-bash">npm run build
</code></pre>
<h2 id="82更新版本号">8.2、更新版本号</h2>
执行如下命令可更新小版本号：
<pre><code class="language-bash">npm version patch
</code></pre>
说明：
<ul>
<li>
patch：小版本号，自动修改最后一位版本号，如1.0.0会修改为1.0.1；
</li>
<li>
minor：中版本号，自动修改中间一位版本号，如1.0.0会修改为1.1.0；
</li>
<li>
major：大版本号，自动修改第一位版本号，如1.0.0会修改为2.0.0；
</li>
</ul>
执行了上述命令后，会自动将package.json中的version增加一个小版本，如下所示：
执行命令前：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303153217211-1918802061.png" alt="image" loading="lazy">
执行命令后：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303153259355-1508453236.png" alt="image" loading="lazy">
<h2 id="83发布到npm仓库">8.3、发布到npm仓库</h2>
接着执行如下命令发布到npm仓库：
<pre><code class="language-bash">npm publish
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303153449388-1261754168.png" alt="image" loading="lazy">
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303153530088-544667757.png" alt="image" loading="lazy">
<hr>
<h1 id="9使用js库">9、使用js库</h1>
此时我们新建一个VUE3测试项目。
执行如下命令修改npm镜像源为淘宝地址：
<pre><code class="language-bash">npm config set registry https://registry.npmmirror.com
</code></pre>
然后我们使用<code>yarn</code>在该测试项目中拉取<code>rapid-test-utls</code>js组件：
<pre><code class="language-bash">yarn add rapid-test-tools
</code></pre>
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303154046615-1329209785.png" alt="image" loading="lazy">
随后我们在App.vue中导入<code>rapid-test-tools</code>中的属性、类型和方法：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303155157828-1775203357.png" alt="image" loading="lazy">
使用属性和方法：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303155228114-370575050.png" alt="image" loading="lazy">
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303155257308-1302264498.png" alt="image" loading="lazy">
同时我们将鼠标放在属性或方法上时，也会有相应的提示信息：
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303155342395-1547125886.png" alt="image" loading="lazy">
<img src="https://img2024.cnblogs.com/blog/346453/202503/346453-20250303155404544-548135044.png" alt="image" loading="lazy">
<hr>
到此，从本地开发js组件、打包组件、发布组件以及使用组件的整个流程就完成了。
<hr>
<h1 id="10发布过程命令">10、发布过程命令</h1>
下面是统一整理的整个发布或更新到npm可能需要用到的命令：
<ul>
<li>
查看npm当前的镜像源
<pre><code class="language-bash">npm config get registry
</code></pre>
</li>
<li>
修改npm镜像源为官网地址
<pre><code class="language-bash">npm config set registry https://registry.npmjs.org
</code></pre>
</li>
<li>
修改npm镜像源为淘宝地址
<pre><code class="language-bash">npm config set registry https://registry.npmmirror.com
</code></pre>
</li>
<li>
打包
<pre><code class="language-bash">npm run build
</code></pre>
</li>
<li>
登录到npm
<pre><code class="language-bash">npm login
</code></pre>
</li>
<li>
首次发布到npm
<pre><code class="language-bash">npm publish --access=public
</code></pre>
</li>
<li>
更新版本号
<pre><code class="language-bash">npm version patch
</code></pre>
<ul>
<li>
patch：小版本号，自动修改最后一位版本号，如1.0.0会修改为1.0.1；
</li>
<li>
minor：中版本号，自动修改中间一位版本号，如1.0.0会修改为1.1.0；
</li>
<li>
major：大版本号，自动修改第一位版本号，如1.0.0会修改为2.0.0；
</li>
</ul>
</li>
<li>
更新发布到npm
<pre><code class="language-bash">npm publish
</code></pre>
</li>
</ul> 
来源：https://www.cnblogs.com/qubernet/p/18744220

頁: [1]

琼殿技术论坛's Archiver

本地新建js公用库组件并打包发布到npm仓库详细说明