dojo dragon main logo

外部依赖

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

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

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

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

{
	"build-app": {
		"externals": {
			"dependencies": [
				"a",
				"b",
				{
					"from": "node_modules/GlobalLibrary.js",
					"to": "GlobalLibrary.js",
					"name": "MyGlobal",
					"inject": true
				},
				{ "from": "src/legacy/layer.js", "to": "legacy/layer.js", "inject": true },
				{
					"from": "node_modules/legacy-dep",
					"to": "legacy-dep/",
					"inject": ["moduleA/layer.js", "moduleA/layer.css", "moduleB/layer.js"]
				}
			]
		}
	}
}

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

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