使用 Rollup 打包 TypeScript SDK 的完整指南

一、Rollup 简介与安装

Rollup 是一个 JavaScript 模块打包器，特别适合库和 SDK 的开发。它通过 Tree-shaking 技术可以生成更小、更高效的代码包。

安装 Rollup

npm install rollup --save-dev
# 或
yarn add rollup -D

二、项目初始化与基础配置

1. 初始化项目结构

project/
├── src/
│   └── index.ts        # 主入口文件
├── dist/               # 打包输出目录
├── test/               # 测试文件
├── rollup.config.mjs   # Rollup 配置文件
└── package.json

2. 核心配置文件解析

package.json 关键配置

{
  "name": "project",
  "version": "1.0.0",
  "main": "dist/project-sdk.cjs.js",
  "module": "dist/project-sdk.esm.js",
  "types": "dist/project-sdk.d.ts",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/project-sdk.esm.js",
      "require": "./dist/project-sdk.cjs.js",
      "types": "./dist/project-sdk.d.ts"
    }
  },
  "scripts": {
     "build": "rollup -c",
     "release": "npm run build && npm publish --access public",
     "test": "mocha -r ts-node/register test/*.test.ts"
  }
}

rollup.config.mjs 配置详解

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import json from '@rollup/plugin-json';
import filesize from 'rollup-plugin-filesize';
import dts from 'rollup-plugin-dts';

export default [
  // 主打包配置
  {
    input: 'src/index.ts',
    output: [
      {
        file: 'dist/project-sdk.cjs.js',
        format: 'cjs',  // CommonJS 格式
        sourcemap: true
      },
      {
        file: 'dist/project-sdk-sdk.esm.js',
        format: 'esm',  // ES Module 格式
        sourcemap: true
      },
      {
        file: 'dist/project-sdk.umd.js',
        format: 'umd',  // 通用模块定义
        name: 'SignZGClientSDK',
        globals: {
          axios: 'axios',
          'crypto-js': 'CryptoJS'
        },
        sourcemap: true
      }
    ],
    plugins: [
      resolve(),       // 解析 node_modules 中的模块
      commonjs(),      // 将 CommonJS 转为 ES6
      typescript(),    // 处理 TypeScript
      json(),          // 支持导入 JSON 文件
      filesize()       // 显示打包文件大小
    ],
    external: ['axios', 'crypto-js']  // 外部依赖
  },
  // 类型声明文件打包
  {
    input: 'src/index.ts',
    output: {
      file: 'dist/project-sdk.d.ts',
      format: 'es'
    },
    plugins: [dts()]  // 生成 .d.ts 文件
  }
];

三、开发环境搭建

1. 安装必要依赖

npm install --save-dev \
  @rollup/plugin-node-resolve \
  @rollup/plugin-commonjs \
  @rollup/plugin-typescript \
  @rollup/plugin-json \
  rollup-plugin-filesize \
  rollup-plugin-dts \
  typescript \
  tslib

2. 安装生产依赖

npm install axios crypto-js jsrsasign qs

四、构建与测试流程

1. 构建 SDK

npm run build

这会生成三种模块格式的文件：

• CommonJS (dist/signzg-client-sdk.cjs.js)

• ES Module (dist/signzg-client-sdk.esm.js)

• UMD (dist/signzg-client-sdk.umd.js)

2. 测试配置

测试依赖安装

npm install --save-dev mocha chai sinon @types/mocha @types/chai ts-node

示例测试文件 test/basic.test.ts

import { expect } from 'chai';
import SDK from '../dist/signzg-client-sdk.esm.js';

describe('SignZGClientSDK', () => {
  it('should initialize correctly', () => {
    const client = new SDK({
      apiKey: 'test-key',
      baseUrl: 'https://api.example.com'
    });
    
    expect(client).to.be.an.instanceOf(SDK);
  });
});

运行测试

npm test

五、本地开发与调试技巧

1. 使用 npm link 进行本地测试

# 在 SDK 项目目录
npm link

# 在测试项目目录
npm link your-package-name

# 取消链接
npm unlink your-package-name

# 在 SDK 项目目录 取消全局
npm unlink

2. 实时重建开发模式

# 监听文件变化并自动重建
rollup -c -w

六、发布准备

1. 版本管理

遵循语义化版本控制 (SemVer):

• major.minor.patch (如 1.0.0)

• 重大更新: npm version major

• 新功能: npm version minor

• Bug 修复: npm version patch

2. 发布到 npm

npm login
npm publish --access public