software

🚀 停止损害你的 Bundle Size

发布: (2025年12月26日 GMT+8 09:11)
5 min read
原文: Dev.to

Source: Dev.to

封面图片描述：左侧显示一个沉重、纠结的 bundle，右侧显示一个干净、直接的导入结构。

我们都喜欢 Barrel Files（即 index.ts 文件，用来从目录中导出所有内容）。它们让我们的导入看起来整洁有序：

// 😍 Looks clean...
import { Button, Header, Footer } from './components';

但这行代码很可能正在 拖慢你的 CI/CD、膨胀你的 bundle 大小，并导致那些令人头疼的 “Module is undefined” 循环依赖错误。

我构建了一个工具来自动修复这些问题，今天就和大家分享。

桶文件的隐藏成本 📉

当你从一个桶文件中导入单个具名导出时，许多打包工具和测试运行器（如 Jest）会加载该桶中所有其他文件来解析模块。

  • 测试变慢 – 在 Jest 中，导入 Button 可能会意外加载 Table、Chart 和 HeavyLibrary，仅仅因为它们共享同一个 index.ts。
  • Tree‑Shaking 失效 – 虽然 Webpack 和 Rollup 正在改进，但深层嵌套的桶文件常常会欺骗它们，把死代码也打包进生产构建。
  • 循环依赖 – 如果模块 A 通过 index 导入模块 B，而模块 B 又通过同一个 index 导入模块 A，就会导致运行时崩溃。

解决方案：直接导入 🛠️

修复很简单，但很繁琐。将以下代码：

import { Button } from './components';

转换为：

import { Button } from './components/Button';

手动对 500 多个文件进行此操作非常痛苦。所以我实现了自动化。

Introducing: no-barrel-file

一个开源的 CLI 工具和 GitHub Action，能够扫描你的项目，查找依赖于 barrel 文件的导入，并 自动重写为直接路径。

✨ 功能

  • 自动修复 – 使用 ts-morph（AST 转换，而非正则）安全地重写导入。
  • 智能 – 尊重你的 tsconfig.json 中的路径和别名。
  • 灵活 – 可以通过 npx 运行，全局安装，或在 CI 中使用。

💻 3 种本地使用方式

方法 1 – “一次性”（无需安装）

检查项目而无需安装依赖的最简方式是使用 npx。

# 仅列出 barrel 文件
npx no-barrel-file display

# 修复 import
npx no-barrel-file replace --alias-config-path tsconfig.json

方法 2 – “项目标准”（开发依赖）

如果希望整个团队都避免 barrel 文件，可以将其作为开发依赖安装。

npm install -D no-barrel-file
# 或者
pnpm add -D no-barrel-file

在 package.json 中添加脚本：

{
  "scripts": {
    "fix:barrels": "no-barrel-file replace --alias-config-path tsconfig.json",
    "check:barrels": "no-barrel-file display"
  }
}

现在团队中的任何人都可以运行 npm run fix:barrels。

方法 3 – “高级用户”（全局安装）

如果你在多个仓库之间工作，并希望在终端的任何位置都能使用此工具：

npm install -g no-barrel-file

# 现在可以在任何地方运行
no-barrel-file display

Source:

🤖 使用 GitHub Actions 自动化

保持代码质量的最佳方式是将其自动化。我发布了一个 GitHub Action，这样你就可以确保没有新的 barrel 文件潜入你的仓库。

选项 A – 自动修复模式（推荐）

此工作流会在 Pull Request 中检测惰性导入，自动修复它们，并将更改推送回分支。

文件: .github/workflows/fix-barrels.yml

name: Auto-Fix Barrel Files
on: [pull_request]

permissions:
  contents: write # Required to commit changes

jobs:
  fix-imports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run No Barrel File
        uses: chintan9/no-barrel-file@v1
        with:
          mode: 'replace'
          alias-config-path: 'tsconfig.json'
          extensions: '.ts,.tsx'

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "refactor: resolve barrel file imports"

选项 B – 审计模式

如果你不想自动修改代码，只想在 CI 日志中获取 barrel 文件的报告：

- name: Audit Barrel Files
  uses: chintan9/no-barrel-file@v1
  with:
    mode: 'display'
    root-path: 'src'

结果

在一个中等规模的 React 项目上运行后，我看到：

  • Jest 启动时间：降低约 30%。
  • 循环依赖错误：完全消失。
  • 打包体积：略有减少（取决于您现有的 tree‑shaking 设置）。

试一试！

我很想听到你的反馈。如果它为你节省了一些时间，请在 GitHub 上给它点星！

[no-barrel-file](https://www.npmjs.com/package/no-barrel-file)

🐙 **GitHub:** [github.com/chintan9/no-barrel-file](https://github.com/chintan9/no-barrel-file)

Happy coding! 🚀
Back to Blog

相关文章

阅读更多 »