parcel-bundler

Parcel Bundler

你是 Parcel 专家。Parcel 是一款零配置的 Web 构建工具。使用 Parcel 项目时，请遵循以下准则。

核心原则

• 默认零配置——Parcel 开箱即用
• 自动检测并安装依赖项
• 内置开发服务器，支持热模块替换
• 基于 Rust 编译器，实现原生性能
• 自动进行代码分割和优化

项目结构

project/
├── src/
│   ├── index.html        # HTML entry point
│   ├── index.js          # JavaScript entry
│   ├── styles.css        # Stylesheets
│   └── assets/           # Images, fonts, etc.
├── dist/                 # Build output (auto-generated)
├── .parcelrc             # Optional configuration
└── package.json

入门

基本用法

# Development with hot reload
parcel src/index.html

# Production build
parcel build src/index.html

package.json 脚本

{
  "scripts": {
    "dev": "parcel src/index.html",
    "build": "parcel build src/index.html",
    "clean": "rm -rf dist .parcel-cache"
  },
  "source": "src/index.html"
}

入口点

HTML 入口

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="./styles.css">
</head>
<body>
  <div id="app"></div>
  <script type="module" src="./index.js"></script>
</body>
</html>

JavaScript 入口

parcel build src/index.js --dist-dir lib

多个入口点

parcel build src/index.html src/admin.html

支持的语言和文件类型

Parcel 开箱即支持：

• JavaScript/TypeScript：.js、.jsx、.ts、.tsx、.mjs
• 样式：.css、.scss、.sass、.less、.styl
• HTML：.html、.htm
• 图像：.png、.jpg、.gif、.svg、.webp
• 字体：.woff、.woff2、.ttf、.otf、.eot
• 数据：.json、.yaml、.toml、.xml
• WebAssembly：.wasm

配置（按需使用）

.parcelrc

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["@parcel/transformer-svg-react"]
  },
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

package.json Targets

{
  "targets": {
    "main": {
      "source": "src/index.js",
      "distDir": "dist",
      "context": "browser",
      "outputFormat": "esm"
    }
  }
}

TypeScript 支持

自动配置

Parcel 会自动处理 TypeScript。只需使用 .ts 或 .tsx 文件。

tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "isolatedModules": true
  }
}

React 支持

自动 JSX

// Parcel handles JSX automatically
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

CSS 和样式

CSS 导入

import './styles.css';

CSS Modules

import * as styles from './Button.module.css';

function Button() {
  return <button className={styles.primary}>Click me</button>;
}

Sass/SCSS

import './styles.scss';

使用 .scss 文件时，Parcel 会自动安装 sass。

资源处理

导入资源

import logo from './logo.png';
import data from './data.json';

// Use in JSX
<img src={logo} alt="Logo" />

URL 引用

const imageUrl = new URL('./image.png', import.meta.url);

代码分割

动态导入

// Automatic code splitting
const LazyComponent = React.lazy(() => import('./LazyComponent'));

// Or manual
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

共享 Bundle

对于多个入口点共用的代码，Parcel 会自动创建共享 Bundle。

环境变量

.env 文件

# .env
API_URL=https://api.example.com

# .env.production
API_URL=https://api.production.com

在代码中使用

const apiUrl = process.env.API_URL;

在 package.json 中定义

{
  "targets": {
    "default": {
      "publicUrl": "/my-app/"
    }
  }
}

开发服务器

默认配置

parcel src/index.html
# Serves at http://localhost:1234

自定义端口

parcel src/index.html --port 3000

HTTPS

parcel src/index.html --https

代理 API 请求

{
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://localhost:8080"
      }
    }
  }
}

生产构建

基本构建

parcel build src/index.html

输出配置

parcel build src/index.html --dist-dir build --public-url /app/

不生成 Source Map

parcel build src/index.html --no-source-maps

优化

自动优化

Parcel 会自动：

• 压缩 JavaScript、CSS、HTML 和 SVG
• 压缩图像
• 生成内容哈希以用于缓存
• 移除未使用的代码
• 对模块进行作用域提升

Bundle 分析

npm install -D parcel-reporter-bundle-analyzer

# Add to .parcelrc
{
  "extends": "@parcel/config-default",
  "reporters": ["...", "parcel-reporter-bundle-analyzer"]
}

缓存

Parcel 使用积极的缓存策略：

# Clear cache
rm -rf .parcel-cache

# Or
parcel build --no-cache

插件开发

插件类型

• 转换器：转换源文件
• 解析器：自定义模块解析
• 打包器：自定义打包逻辑
• 命名器：自定义输出命名
• 封装器：封装 Bundle
• 优化器：优化 Bundle
• 报告器：自定义构建报告

插件规则

1. 无状态：避免使用内部状态
2. 纯函数：相同的输入产生相同的输出
3. 无副作用：不要修改外部状态

库开发

Package.json 配置

{
  "name": "my-library",
  "source": "src/index.ts",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "types": "dist/types.d.ts",
  "targets": {
    "main": {
      "outputFormat": "commonjs"
    },
    "module": {
      "outputFormat": "esmodule"
    },
    "types": {
      "source": "src/index.ts"
    }
  }
}

最佳实践

建议

• 从零配置开始
• 让 Parcel 处理资源优化
• 使用动态导入进行代码分割
• 利用自动依赖安装
• 使用 CSS Modules 编写组件样式

避免

• 默认配置可用时仍过度配置
• 违背 Parcel 的约定
• 手动优化 Parcel 已处理的内容
• 忽略构建警告和错误

常见模式

单页应用

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./index.tsx"></script>
</body>
</html>

静态网站

parcel build src/*.html

Web Worker

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module'
});

故障排除

清除缓存

rm -rf .parcel-cache dist

详细输出

parcel build --log-level verbose

调试模式

DEBUG=parcel:* parcel build

从其他打包器迁移

• 删除 webpack.config.js 或类似配置文件
• 删除加载器/插件依赖项
• 如有需要，更新导入语句
• Parcel 会自动安装所需依赖项