npm 发布流程——从创建组件到发布到 npm 仓库

1. 准备组件

1.1 创建一个 Vue 组件

假设我们要创建一个简单的按钮组件：

src/MyButton.vue

<template>
  <button class="my-btn" @click="$emit('click')">
    <slot />
  </button>
</template>

<script setup lang="ts">
  // 可以在这里加 props
</script>

<style scoped>
.my-btn {
  padding: 8px 16px;
  background: #42b983;
  color: white;
  border-radius: 4px;
  cursor: pointer;
}
</style>

2. 项目结构和 package.json 配置

2.1 项目结构

my-button-component/
├─ src/
│  └─ MyButton.vue
├─ dist/              # 打包后的文件（发布到 npm 后包含的文件）
├─ package.json       # npm 包配置
├─ vite.config.ts     # Vite 配置（用来打包组件）
├─ .npmignore         # 发布时忽略不需要的文件
└─ README.md          # 组件说明

2.2 package.json 配置

你需要配置 package.json，确保别人能够正确安装和使用组件。最重要的是配置好 入口文件 和 类型声明。

{
  "name": "@your-username/my-button",  // 组件的 npm 包名（如果是私有发布需要用组织名）
  "version": "1.0.0",
  "main": "dist/index.cjs.js",         // CommonJS 入口
  "module": "dist/index.esm.js",       // ES Module 入口
  "types": "dist/index.d.ts",          // 类型声明
  "scripts": {
    "build": "vite build"              // 构建命令
  },
  "peerDependencies": {
    "vue": "^3.0.0"                    // 依赖 Vue
  },
  "devDependencies": {
    "vite": "^3.0.0",                  // 构建工具
    "typescript": "^4.0.0",            // TypeScript 支持
    "@vitejs/plugin-vue": "^3.0.0"     // Vue 插件
  },
  "keywords": ["vue", "component", "button"],
  "author": "Your Name",
  "license": "MIT"
}

2.3 .npmignore 文件

你需要确保不把 src/、node_modules/ 和一些不必要的文件（例如测试文件、文档等）发布到 npm 上。你可以在 .npmignore 中指定这些文件。

.npmignore

src/            # 源代码文件夹
node_modules/   # 不需要发布 node_modules
example/        # 示例文件夹
.vscode/         # 编辑器配置
.git/           # Git 配置
tests/          # 测试文件
README.md       # 可选，通常 README 会发布到 npm

3. 配置构建工具（Vite）

为了让 Vue 组件能够正确地打包成 npm 包，你可以使用 Vite 来打包它。

3.1 安装 Vite 和相关依赖

首先安装 Vite 和 Vue 插件，便于构建和打包 Vue 组件。

npm install vite @vitejs/plugin-vue --save-dev

3.2 配置 vite.config.ts

在根目录下创建 vite.config.ts 来配置 Vite 打包，确保它正确打包 Vue 组件并生成类型声明文件。

vite.config.ts

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import dts from "vite-plugin-dts";  // 用来生成类型声明文件

export default defineConfig({
  plugins: [vue(), dts()],
  build: {
    lib: {
      entry: "src/index.ts",   // 入口文件
      name: "MyButton",        // 全局变量名（UMD格式）
      fileName: "index",       // 输出的文件名
    },
    rollupOptions: {
      external: ["vue"],       // 确保 Vue 作为外部依赖，不打包进来
      output: {
        globals: {
          vue: "Vue",           // UMD 格式时，全局变量名称
        },
      },
    },
  },
});

3.3 创建 src/index.ts 文件

src/index.ts

import MyButton from "./MyButton.vue";

// 作为模块导出
export { MyButton };

// 或者提供一个 install 方法以支持全局注册
import type { App } from "vue";
export default {
  install(app: App) {
    app.component("MyButton", MyButton);
  },
};

4. 本地测试

在发布之前，你可以通过本地测试来验证组件是否能够正常工作。

4.1 创建一个本地测试项目（可选）

在本地创建一个简单的 Vue 项目，然后从你的组件库中导入并测试：

cd example
npm install ../my-button-component

<template>
  <MyButton @click="handleClick">点击我</MyButton>
</template>

<script setup>
import { MyButton } from "@your-username/my-button";

const handleClick = () => {
  console.log("按钮被点击了");
};
</script>

4.2 运行本地测试

在本地测试是否一切正常。如果都可以正常使用，就可以继续发布。

5. 发布到 npm

5.1 登录 npm

如果你还没有登录 npm，你需要先执行登录命令：

npm login

5.2 打包并发布

运行以下命令进行打包，并发布到 npm：

npm run build
npm publish --access public

如果是私有包，可以改成：

npm publish --access restricted

6. 其他建议

• 版本管理：每次修改组件时，需要更新 package.json 中的 version，遵循语义化版本（SemVer）规则：major.minor.patch。
• README.md：在 README.md 中写好文档，描述组件的用法、安装方式、配置选项等。
• CI/CD：可以设置 CI/CD 来自动化打包和发布，比如使用 GitHub Actions 或 GitLab CI 来实现。

7. 使用

发布成功后，别人就可以通过 npm 安装并使用你的组件了：

npm install @your-username/my-button

然后就可以在 Vue 项目中这样使用：

<template>
  <MyButton @click="handleClick">点击我</MyButton>
</template>

<script setup>
import { MyButton } from "@your-username/my-button";

const handleClick = () => {
  console.log("按钮被点击了");
};
</script>

这样，整个 发布到 npm 的流程就完成了！你可以根据需要随时更新和发布新版本。