TypeScript库编译发布异常：Webpack/TSC编译失败及NPM配置求助

我完全懂你现在的困扰——想把自己写的基于Rx流的对象状态追踪TypeScript库发布到NPM，既要编译成单个JS文件、生成TypeScript声明文件，又要确保发布时只推dist文件夹方便用户调试，但用Webpack或者单纯TSC都搞不定对吧？别慌，我给你一套靠谱的配置方案，一步步来就能解决。

一、用Rollup+TSC实现单文件编译与声明文件生成 #

单纯TSC默认会把每个TS文件编译成单独的JS模块，没法打包成单个文件；Webpack则更适合应用打包，给库打包会带一堆冗余的runtime代码。用Rollup搭配TypeScript插件是目前打包TS库的最优解，能完美生成单文件JS和对应的.d.ts声明。

1. 先装依赖 #

打开终端跑这条命令，安装需要的工具：

npm install rollup rollup-plugin-typescript2 typescript rxjs --save-dev

（这里默认你依赖rxjs，要是有其他依赖也可以按需添加）

2. 配置tsconfig.json #

调整你的TypeScript编译配置，确保能生成声明文件：

{
  "compilerOptions": {
    "target": "ES2018", // 选合适的目标ES版本，兼顾兼容性和新特性
    "module": "ESNext",
    "declaration": true, // 开启声明文件生成
    "declarationDir": "./dist/types", // 声明文件输出到dist/types下
    "outDir": "./dist", // 编译后的JS文件输出目录
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "Node"
  },
  "include": ["src/**/*"], // 只编译src下的代码
  "exclude": ["node_modules", "dist"]
}

3. 写Rollup配置文件（rollup.config.js） #

这个文件负责把你的TS代码打包成单个JS文件，同时处理声明文件：

import typescript from 'rollup-plugin-typescript2';

export default {
  input: 'src/index.ts', // 替换成你的库入口文件路径
  output: [
    {
      file: 'dist/index.cjs.js', // 生成CommonJS格式，适合Node环境
      format: 'cjs'
    },
    {
      file: 'dist/index.esm.js', // 生成ES模块格式，适合浏览器或现代Node环境
      format: 'es'
    }
  ],
  plugins: [
    typescript({
      tsconfig: './tsconfig.json',
      useTsconfigDeclarationDir: true // 遵循tsconfig里的声明文件目录配置
    })
  ],
  external: ['rxjs'] // 把rxjs设为外部依赖，不打包进你的库，让用户自己安装
};

4. 添加编译脚本到package.json #

在package.json的scripts里加一条build命令，方便一键编译：

"scripts": {
  "build": "rollup -c && cp package.json dist/ && cp README.md dist/"
}

这里额外复制了package.json和README到dist里，这样用户安装你的库时能看到说明和包配置。

二、配置NPM发布仅推送dist文件夹 #

接下来要确保执行npm publish时，只有dist文件夹被推送到NPM仓库，其他源码、配置文件都不发。

1. 调整根目录的package.json #

添加这些字段，明确包的入口和发布范围：

"files": [
  "dist"
],
"main": "dist/index.cjs.js", // CommonJS入口
"module": "dist/index.esm.js", // ES模块入口
"types": "dist/types/index.d.ts", // TypeScript声明文件入口
"exports": {
  ".": {
    "require": "./dist/index.cjs.js",
    "import": "./dist/index.esm.js",
    "types": "./dist/types/index.d.ts"
  }
}

files字段直接指定了发布时要包含的文件夹，比用.npmignore更直观可靠。

2. 可选：用.npmignore兜底（不推荐但可用） #

如果你不想用files字段，也可以在根目录创建.npmignore文件，写上要排除的内容：

node_modules/
src/
rollup.config.js
tsconfig.json
.gitignore

不过还是更推荐用files字段，能避免不小心漏写排除项。

三、测试发布流程 #

先别着急发布，本地测试一遍确保没问题：

1. 执行编译命令：

npm run build

2. 进入dist文件夹，生成测试包：

cd dist
npm pack

这会生成一个.tgz格式的包，你可以在本地项目里安装测试：

npm install ../your-library-name-1.0.0.tgz

3. 确认库能正常导入使用、类型提示也没问题后，就可以发布了：

npm publish

为啥不推荐单纯用TSC或Webpack？ #

• 单纯TSC：只能把每个TS文件编译成单独的JS，没法合并成单个文件，用户用起来要导入多个模块，体验不好。
• Webpack：打包库会引入自身的runtime代码，增大包体积，而且处理TypeScript声明文件的流程不如Rollup顺畅。

内容的提问来源于stack exchange，提问作者Lihai