• ? API
    • Bundler
      • 事件
      • Bundle
        • 属性
        • 树
          • 资源树：
          • Bundle 树:
      • 中间件(Middleware)
    • 帮助我们改善文档

    ? API

    Bundler

    你可以选择使用 API 替代 CLI 来初始化 bundler 对象，以获取更高级的使用方式(例如：在每次构建时进行自定义操作)。针对每个选项都给出了可参考的示例进行解释说明：

    1. const Bundler = require('parcel-bundler');
    2. const Path = require('path');
    4. // 单个入口文件路径
    5. const entryFiles = Path.join(__dirname, './index.html');
    6. // 或多个入口文件路径
    7. // 1.glob模式
    8. const entryFiles = './src/*.js';
    9. // 2.数组格式
    10. const entryFiles = ['./src/index.html', './some/other/directory/scripts.js'];
    12. // Bundler 选项
    13. const options = {
    14.   outDir: './dist', // 将生成的文件放入输出目录下，默认为 dist
    15.   outFile: 'index.html', // 输出文件的名称
    16.   publicUrl: './', // 静态资源的 url ，默认为 '/'
    17.   watch: true, // 是否需要监听文件并在发生改变时重新编译它们，默认为 process.env.NODE_ENV !== 'production'
    18.   cache: true, // 启用或禁用缓存，默认为 true
    19.   cacheDir: '.cache', // 存放缓存的目录，默认为 .cache
    20.   contentHash: false, // 禁止文件名hash
    21.   global: 'moduleName', // 在当前名字模块以UMD模式导出，默认禁止。
    22.   minify: false, // 压缩文件，当 process.env.NODE_ENV === 'production' 时，会启用
    23.   scopeHoist: false, // 打开实验性的scope hoisting/tree shaking用来缩小生产环境的包。
    24.   target: 'browser', // 浏览器/node/electron, 默认为 browser
    25.   bundleNodeModules: false, // 当package.json的'target'设置'node' or 'electron'时，相应的依赖不会加入bundle中。设置true将被包含。
    26.   https: { // 设置true自动定义一对密钥和证书，false取消变成http
    27.     cert: './ssl/c.crt', // 自定义证书路径
    28.     key: './ssl/k.key' // 自定义密钥路径
    29.   },
    30.   logLevel: 3,
    31.   /**
    32.    * 5 = 储存每个信息
    33.    * 4 = 输出信息、警告和错误附加时间戳和dev服务的http请求
    34.    * 3 = 输出信息、警告和错误
    35.    * 2 = 输出警告和错误
    36.    * 1 = 输出错误
    37.   */
    38.   hmr: true, // 开启或禁止HRM
    39.   hmrPort: 0, // hmr socket 运行的端口，默认为随机空闲端口(在 Node.js 中，0 会被解析为随机空闲端口)
    40.   sourceMaps: true, // 启用或禁用 sourcemaps，默认为启用(在精简版本中不支持)
    41.   hmrHostname: '', // 热模块重载的主机名，默认为 ''
    42.   detailedReport: false // 打印 bundles、资源、文件大小和使用时间的详细报告，默认为 false，只有在禁用监听状态时才打印报告
    43. };
    45. (async function() {
    46.   // 使用提供的入口文件路径和选项初始化 bundler
    47.   const bundler = new Bundler(entryFiles, options);
    49.   // 运行 bundler，这将返回主 bundle
    50.   // 如果你正在使用监听模式，请使用下面这些事件，这是因为该 promise 只会触发一次，而不是每次重新构建时都触发
    51.   const bundle = await bundler.bundle();
    52. })();

    你可以使用 bundler.serve() 启动内建于 Parcel 的开发服务器。bundler.serve()会调用bundler.bundle()启动一个简易的 HTTP/HTTPS 服务器。serve()接受三个非必填参数，第一个是端口，第二个是启动 https（可以设置为一个{cert, key}对象指向 key 和 cert 的路径或者 true 自动生成证书），第三个是主机地址 host。

    事件

    这是所有的 bundler 事件列表。

    • 一旦 parcel 完成打包，会调用 bundled，主 bundle 会作为参数传递到该 callback
    1. const bundler = new Bundler(...);
    2. bundler.on('bundled', (bundler) => {
    3.   // bundler 包含所有资源和 bundle，如需了解更多请查看文档
    4. });
    5. // 开始构建调用
    6. bundler.bundle();
    • 每次构建结束后，都会调用 buildEnd，即使发生错误它也仍然会被触发
    1. const bundler = new Bundler(...);
    2. bundler.on('buildEnd', () => {
    3.   // 做一些操作……
    4. });
    5. // 开始构建调用
    6. bundler.bundle();
    • 首次构建会调用 buildStart，entryFiles数组作为参数传递给回调函数
    1. const bundler = new Bundler(...);
    2. bundler.on('buildStart', entryPoints => {
    3.   // 做一些操作……
    4. });
    5. // 开始构建调用
    6. bundler.bundle();
    • 构建中出现的错误都会调用 buildError，Error对象作为参数传递给回调函数。
    1. const bundler = new Bundler(...);
    2. bundler.on('buildError', error => {
    3.   // 做一些操作……
    4. });
    5. // 开始构建调用
    6. bundler.bundle();

    Bundle

    Bundle 是 parcel 用来将资源打包在一起的工具，它还包含能够构建出 bundle 树的子 bundle 和兄弟 bundle。

    属性

    • type：它包含的资源类型 (例如：js, css, map, …)
    • name：bundle 的名称 (使用 entryAsset 的 Asset.generateBundleName() 生成)
    • parentBundle：父 bundle ，入口 bundle 的父 bundle 是 null
    • entryAsset：bundle 的入口，用于生成名称(name)和聚拢资源(assets)
    • assets：bundle 中所有资源的集合(Set)
    • childBundles：所有子 bundle 的集合(Set)
    • siblingBundles：所有兄弟 bundle 的集合(Set)
    • siblingBundlesMap：所有兄弟 bundle 的映射 Map<String(Type: js, css, map, …), Bundle>
    • offsets：所有 bundle 中资源位置的映射 Map<Asset, number(line number inside the bundle)> ，用于生成准确的 sourcemap 。

    树

    Bundle 包含一个 parentBundle，childBundles 和 siblingBundles，所有这些属性一起创建一个快速迭代的 bundle 树。

    资源树及其生成的 bundle 树的基本示例如下:

    资源树：

    index.html 引用 index.js 和 index.css

    index.js 引用 test.js 和 test.txt

    1. index.html
    2. -- index.js
    3.  |--- test.js
    4.  |--- test.txt
    5. -- index.css
    Bundle 树:

    index.html 被作为主 bundle 的入口资源，这个主 bundle 创建了两个子 bundle ，一个用于 index.js，另一个用于 index.css ，这是因为它们与 html 的类型不同。

    index.js 引入了两个文件，test.js 和 test.txt。

    test.js 被添加到了 index.js bundle 的资源中，因为它与 index.js 的类型相同。

    test.txt 会创建一个新的 bundle，并被添加到 index.js bundle 的子元素中，因为它是与 index.js 不同的资源类型。

    index.css 没有引用资源，因此只包含它的入口资源。

    index.css 和 index.js 这两个 bundle 为共享同一父 bundle 的兄弟 bundle(siblingBundles)。

    1. index.html
    2. -- index.js (includes index.js and test.js)
    3.  |--- test.txt (includes test.txt)
    4. -- index.css (includes index.css)

    中间件(Middleware)

    中间件可以用于 hook 到 http 服务器(例如：express 或者 Node.js http) 。

    使用 express 的 parcel 中间件示例：

    1. const Bundler = require('parcel-bundler');
    2. const app = require('express')();
    4. const file = 'index.html'; // 传入一个绝对路径，作为入口文件
    5. const options = {}; // 有关 options 的具体配置，请参考 api 文档
    7. // 使用 file 和 options 参数，初始化新的 bundler
    8. const bundler = new Bundler(file, options);
    10. // 让 express 使用 bundler 中间件，这将让 parcel 处理你 express 服务器上的每个请求
    11. app.use(bundler.middleware());
    13. // 监听 8080 端口
    14. app.listen(8080);

    帮助我们改善文档

    如果有遗漏或者不清楚的地方，请在本站的仓库 提交issue 或者 编辑此页面.