乐趣区

关于cesium:为何在打包工具中导入-Cesium-的-css-失败了

jiezi

1 问题起因

我应用 vite2 + vanillajs 模板创立 CesiumJS 我的项目，其中，main.js 是这样的：

import {Viewer} from 'cesium'
import './style.css'
import 'cesium/Source/Widgets/widgets.css'

let viewer
const main = () => {const dom = document.getElementById('app')
  viewer = new Viewer(dom)
}

document.addEventListener('DOMContentLoaded', () => {main()
})

看起来逻辑完满，思路清晰，没什么特地的疑难点。于是我就吭哧吭哧地运行起 npm script：

pnpm dev

可是，Vite 在控制台给我报了个错：

[vite] Internal server error: Missing "./Source/Widgets/widgets.css" export in "cesium" package

这个问题貌似在各前端框架的模板中是不会呈现的，我不确定。也有人在 Webpack 中遇到了这个相似的状况，究其原因，我认为还是 cesium 包的导出有些不齐备，见上面第二节的剖析。

简略点说，就是 Vite 的内置预构建工具 esbuild 在搜寻依赖树时，没有找到 "cesium" 包导出的一个门路为 "./Source/Widgets/widgets.css" 文件。

2 寻找解决方案

可是，当我关上 node_modules/cesium/Source/Widgets/ 目录，widgets.css 文件确实就在那里放着。

于是我关上了谷歌，果不其然找到了相似的 issue：github.com/CesiumGS/cesium issue#9212，我在 2021 年 8 月也跟帖回复了我的状况。

我过后并没有找到解决方案，就临时跳过了。

起初，有外国敌人跟帖回复，大抵起因找到了：

cesium 包的 package.json 没有导出款式文件，次要是 package.json 中的 exports 属性。

于是，我关上官网源码的 package.json，找到对应的局部：

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": "./index.cjs",
      "import": "./Source/Cesium.js"
    }
  }
}

2.1. 历史起因

家喻户晓，NodeJS 最先应用的模块化机制是 CommonJS，起初才反对的 ESModule，当初 NodeJS 依然默认新建的包是 CommonJS 模块的。

外国佬在 NodeJS 的包中容许双模块化，这就容易存在兼容性问题。咱们看看最开始是怎么实现双模块化的，这里以默认 ESModule 为模块化形式：

  • 设置 package.json 的 "type": "module"，这样所有的 .js 文件都是 ESM 了
  • 设置 package.json 的 "module": "./dist/esm/index.js"，这个意思是应用 import 语法导入时，ESM 模块将从哪里寻找主文件
  • 设置 package.json 的 "main": "./index.cjs"，这个意思是应用 require 函数导入模块时，CommonJS 的主文件是哪个

起初，随着 ESModule 成为支流规范，NodeJS 改良了下面的配置形式，你仍能够设置 "type": "module" 令以后包的模块化是 ESM，然而对包的多模块化机制的配置则改用了 "exports" 字段，正如下面 cesium 的配置。

我查看了我的 NodeJS 版本：

> node -v
> v16.14.0

显然比拟新，那么它应该就是从 "exports" 中读取的导出信息。

2.2. 减少导出

于是，我减少了 "exports" 的导出字段，让打包工具在辨认 cesium 包的导出时，能够正确辨认 widgets.css 文件。

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": "./index.cjs",
      "import": "./Source/Cesium.js"
    },
+   "./Source/Widgets/widgets.css": "./Source/Widgets/widgets.css"
  }
}

这样，上面两个导入语句：

import {Viewer} from 'cesium'
import 'cesium/Source/Widgets/widgets.css'

实际上就是：

import {Viewer} from 'cesium/Source/Cesium.js'
import 'cesium/Source/Widgets/widgets.css'

2.3. 耍个把戏

我感觉这样导入 css 文件还是太长，无妨在 "exports" 中给它改个名：

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": "./index.cjs",
      "import": "./Source/Cesium.js"
    },
+   "./index.css": "./Source/Widgets/widgets.css"
  }
}

而后就能够欢快地应用短门路导入了：

import {Viewer} from 'cesium'
import 'cesium/index.css'

事实上，package.json 中的这个 exports 属性，就起到相似导出别名的作用，其中 "." 就相当于包的根门路。

3 类型提醒是哪来的

思考这样导入 cesium 各个 API：

import {
  Viewer,
  Cartesian3,
  Camera
} from 'cesium'

当你应用这些类的时候，会失去不错的类型提醒。回顾后面的内容，其实从 "cesium" 导入子模块，实际上是从 "cesium/Source/Cesium.js" 文件导入的，而这个文件的旁边就有一个 "Cesium.d.ts" 文件，它就起类型提醒的作用。

这个类型申明文件是 Cesium 应用 gulp 打包时输入的。

说了这么多，根本原因还是 JavaScript 的历史包袱导致的各种问题，而且官网也临时没有批改 package.json 中 exports 的打算，如果你有报这个谬误，那么你仅仅须要按我下面的形式稍作批改即可。

退出移动版