外部依赖

通常不能被打包的非模块化库或者独立的应用程序，如果需要引入到 dojo 应用程序中，则可以通过提供一个 require 或 define 实现，并在项目的 .dojorc 文件中做一些配置。

要配置外部依赖项，则需要为 build-app 配置对象设置 externals 属性。externals 是一个对象，包含以下两个属性：

  • outputPath: 一个可选属性，指定一个将文件复制到何处的输出路径。
  • dependencies: 一个必填的数组，定义哪些模块应该通过外部加载器加载，以及在构建时应该包含哪些文件。每个记录可以是以下两种类型之一：
    • 一个字符串，表示应该使用外部加载器加载此路径及其所有子路径。
    • 一个对象，为需要复制到构建版应用程序的依赖提供附加配置项。此对象具有以下属性：
属性类型可选描述
fromstring否相对于项目根目录的路径，指定位于何处的文件夹或目录要复制到已构建应用程序中。
tostring是一个路径，表示将 from 路径下的依赖复制到何处的目标路径。默认情况下，依赖会被复制到 ${externalsOutputPath}/${to}；如果没有设置 to，依赖会被复制到 ${externalsOutputPath}/${from}。如果路径中包含 . 字符或者路径表示的是一个文件夹，则需要以正斜杠结尾。
namestring是在应用程序代码中引用的模块 id 或者全局变量名。
injectstring, string[], or boolean是此属性表示这个依赖定义的（或者包含的），要在页面中加载的脚本或样式文件。如果 inject 的值为 true，那么就会在页面中加载 to 或 from 指定位置的文件。如果依赖的是文件夹，则 inject 可以被设置为一个或者一组字符串，来定义一个或多个要注入的文件。inject 中的每个路径都应该是相对于 ${externalsOutputPath}/${to} 或 ${externalsOutputPath}/${from}（具体取决于是否指定了 to）。
type‘root’ or ‘umd’ or ‘amd’ or ‘commonjs’ or ‘commonjs2’是强制模块用指定的方法解析。如果是 AMD 风格，则必须使用 umd 或 amd。如果是 node 风格则必须使用 commonjs，并且值为 root 时以全局的方式访问对象。

例如，以下配置会将 src/legacy/layer.js 注入到应用程序页面中；注入定义了 MyGlobal 全局变量的文件；声明模块 a 和 b 为外部依赖，且要委托给外部层；然后复制 node_modules/legacy-dep 下的文件，并将其中的几个文件注入到页面中。所有文件都将被复制到 externals 文件夹中，也可以使用 externals 配置中的 outputPath 属性来重新指定文件夹。

  1. {
  2.     "build-app": {
  3.         "externals": {
  4.             "dependencies": [
  5.                 "a",
  6.                 "b",
  7.                 {
  8.                     "from": "node_modules/GlobalLibrary.js",
  9.                     "to": "GlobalLibrary.js",
  10.                     "name": "MyGlobal",
  11.                     "inject": true
  12.                 },
  13.                 { "from": "src/legacy/layer.js", "to": "legacy/layer.js", "inject": true },
  14.                 {
  15.                     "from": "node_modules/legacy-dep",
  16.                     "to": "legacy-dep/",
  17.                     "inject": ["moduleA/layer.js", "moduleA/layer.css", "moduleB/layer.js"]
  18.                 }
  19.             ]
  20.         }
  21.     }
  22. }

externals 中包含的依赖项的类型会被安装到 node_modules/@types 中，这跟其它依赖项是一样的。

因为这些文件位于主构建（main build）之外，所以在生产构建中不会执行版本控制或哈希处理（在 inject 中指定资源的链接除外）。可以在 to 属性中指定版本号，将依赖复制到对应版本的文件夹下，这样就能避免缓存不同版本的文件。