核心概念：合并 vs. 编译

首先要明确,我们通常说的“合并”在 TypeScript 语境下，指的是编译过程。tsc 编译器会做以下几件事：

1. 类型检查：检查你的代码是否符合 TypeScript 的类型规范。
2. 转换：将 TypeScript 语法（如 interface, enum, 类型注解）转换成 JavaScript 语法。
3. 模块解析与打包：根据你配置的模块系统（module），将多个源文件（.ts）的依赖关系解析并输出到一个或多个目标文件（.js）中。

我们讨论的其实是“如何配置 TypeScript 编译器，将多个 .ts 文件编译合并成 .js 文件”。

使用 TypeScript 编译器 (tsc) - 基础方法

这是最直接的方法,使用 TypeScript 自带的命令行工具。

初始化项目并安装 TypeScript

如果你的项目还没有 tsconfig.json 文件，需要先初始化一个。

# 初始化 npm 项目
npm init -y
# 安装 TypeScript 作为开发依赖
npm install --save-dev typescript

创建 tsconfig.json 配置文件

在项目根目录下运行以下命令,会生成一个默认的 tsconfig.json 文件。

npx tsc --init

修改 tsconfig.json 以实现“合并”

关键在于配置 tsconfig.json 中的几个选项，打开这个文件，找到并修改（或取消注释）以下几行：

{
  "compilerOptions": {
    /* ... 其他配置 ... */
    // 1. 指定编译的入口文件
    // "files": ["src/index.ts"], // 适用于少量文件
    // 或者使用 "include" 来指定一个目录下的所有 .ts 文件（推荐）
    "include": ["src/**/*"],
    // 2. 指定编译输出的目录
    "outDir": "./dist",
    // 3. 指定模块系统，这决定了如何“合并”文件
    // "CommonJS" 是 Node.js 的标准，所有代码最终会合并到少数几个文件中
    // "ESNext" 会保持 ES 模块格式，每个文件可能对应一个 .js 文件
    "module": "CommonJS",
    // 4. 关键选项：将所有非入口模块（依赖）打包到单个输出文件中
    // 当 module 为 "CommonJS" 时，这个选项才有效
    "outFile": "./dist/bundle.js", 
    /* ... 其他配置 ... */
  }
}

配置详解：

• include: 告诉编译器去哪个目录下寻找 .ts 文件。["src/**/*"] 表示包含 src 目录及其所有子目录下的所有文件。
• outDir: 编译后的 .js 文件存放的目录。
• module: 定义代码的模块系统。
  • "CommonJS": 使用 require 和 module.exports，这是 Node.js 的标准。
  • "ESNext" (或 "ES2025"): 使用 import 和 export 语法。
• outFile: 这是实现“合并”的核心选项。
  • 当你设置了 outFile，module 为 "CommonJS" 时，tsc 会将所有通过 include 找到的文件，按照它们的依赖关系，全部编译并合并到 outFile 指定的单个 .js 文件中。
  • 注意：outFile 不适用于 module 为 "ESNext" 的情况，因为 ES 模块本身就是基于文件的。

运行编译命令

在 package.json 的 scripts 中添加一个编译命令：

"scripts": {
  "build": "tsc"
}

然后执行：

npm run build

执行后,你会在 dist 目录下看到一个 bundle.js 文件，这就是合并后的结果。

使用模块打包工具 (Webpack / Rollup / Vite) - 现代前端项目首选

对于现代前端项目,我们通常使用打包工具，它们不仅能处理 TypeScript，还能处理 CSS、图片、Sass 等资源，并提供了代码分割、Tree Shaking（摇树优化）、热更新等强大功能。

这里以 Webpack 为例。

安装依赖

# 安装 webpack 和相关 loader
npm install --save-dev webpack webpack-cli ts-loader
# 或者如果你喜欢使用 TypeScript 插件
npm install --save-dev webpack webpack-cli ts-loader typescript

创建 webpack.config.js

在项目根目录下创建 webpack.config.js 文件：

const path = require('path');
module.exports = {
  // 模式：'development' 或 'production'
  mode: 'production', // 'production' 会自动压缩代码
  // 入口文件
  entry: './src/index.ts',
  // 输出配置
  output: {
    // 输出文件名
    filename: 'bundle.js',
    // 输出目录
    path: path.resolve(__dirname, 'dist'),
  },
  // 解析 .ts 文件
  resolve: {
    extensions: ['.ts', '.js'], // 自动解析这些后缀的文件
  },
  // 模块加载规则
  module: {
    rules: [
      {
        test: /\.ts$/, // 匹配所有 .ts 文件
        use: 'ts-loader', // 使用 ts-loader 编译 TypeScript
        exclude: /node_modules/,
      },
    ],
  },
};

创建 tsconfig.json

和之前一样,你需要一个 tsconfig.json 文件来配置 TypeScript 编译选项，但这里的配置可以更简单，因为 Webpack 负责了模块合并和打包的工作。

{
  "compilerOptions": {
    "target": "es5", // 编译成哪个版本的 JS
    "module": "esnext", // 告诉 ts-loader 使用 ES 模块语法
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist", // 可选，tsc 也可以输出到 dist
    "rootDir": "./src"  // 可选，指定源文件根目录
  },
  "include": ["src/**/*"]
}

运行打包命令

在 package.json 中添加脚本：

"scripts": {
  "build": "webpack"
}

执行命令：

npm run build

Webpack 会从 src/index.ts 开始，分析所有 import 依赖，并将所有相关代码打包到 dist/bundle.js 中。

使用 Vite - 现代化、极速的前端构建工具

Vite 是目前非常流行的前端构建工具，它利用浏览器原生的 ES 模块支持，实现了极冷的服务器启动速度。

安装依赖

# 创建一个基于 TypeScript 的 Vite 项目
npm create vite@latest my-vue-ts-app -- --template vue-ts
# 或者进入项目后安装依赖
cd my-vue-ts-app
npm install

配置和运行

Vite 的配置非常简单，项目根目录下的 vite.config.ts 文件就是它的配置文件。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  // 可以在这里配置构建选项
  build: {
    // 输出文件名
    rollupOptions: {
      output: {
        manualChunks: undefined, // 可以自定义代码分割
      }
    }
  }
})

运行命令

Vite 提供了开箱即用的命令：

# 开发模式，启动一个热更新服务器
npm run dev
# 生产环境构建
npm run build

执行 npm run build 后，Vite 会将你的项目打包到 dist 目录，默认情况下，它会将代码分割成多个文件（vendor chunk 和你的业务代码 chunk），以实现更好的缓存，如果你想合并成一个文件，可以在 vite.config.ts 中配置：

// vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        // 将所有代码打包到一个文件中
        manualChunks: undefined, // 确保没有自定义分割
        // 可选：指定输出文件名
        entryFileNames: 'bundle.js',
        chunkFileNames: 'bundle.js',
        assetFileNames: 'bundle.js'
      }
    }
  }
})

总结与选择建议

• 如果你只是写一个简单的 Node.js 脚本或工具，用 tsc 配合 outFile 就足够了。
• 如果你正在开发一个现代 Web 应用（Vue, React, Svelte 等），强烈推荐使用 Vite，它的开发体验是无与伦比的。
• 如果你正在维护一个庞大且复杂的项目,或者有非常特殊的构建需求，Webpack 依然是可靠的选择。