Nuxt3使用Cropperjs2.0如何实现SSR，内有方案？

经常使用 `Nuxt3` 的朋友们，一定经常遇到很多库与SSR不兼容的问题，这不 `CroppingJS` 就算一个。

最近 `CroppingJS` 发布了 `2.0` 版本，使用TS完全重构了代码，并封装了很多HTML自定义标签，但很遗憾，仍然与SSR有冲突！

<!-- more -->

## 请看解决方案

```html
<script setup lang="ts">
import type { CropperCanvas, CropperViewer, CropperSelection, CropperImage } from 'cropperjs';

onMounted(async () => {
  // 动态导入 Cropper.js，确保只在客户端加载
  const Cropper = (await import("cropperjs")).default;

  await import("cropperjs");
});
</script>
```

*此时，你可以拿着这段代码关闭本页面了，但你如果想要深造一下，可以往下看！*

> 前排提示，这段代码是 `Grok3` 告诉我的，我不懂，那只能让 `Grok3` 给我讲讲了！


## 解决 SSR 问题的核心思路

这段代码的核心思路是通过 **延迟执行** 和 **动态导入**，将依赖浏览器环境的代码（如 Cropper.js）限制在客户端运行，从而避免服务器端渲染时因缺少 DOM 环境而产生的错误。以下是详细的拆解：

### 1. 使用 onMounted 延迟执行

- **onMounted 的作用**：onMounted 是 Vue 的生命周期钩子，只有在组件挂载到 DOM 后才会触发。而在 SSR（服务器端渲染）环境中，服务器只负责生成初始 HTML，不会执行组件的挂载逻辑。因此，onMounted 内的代码不会在服务器端运行，只会在客户端执行。
- **为什么重要**：Cropper.js 是一个依赖浏览器 DOM API 的库（例如操作 `<img>` 元素），而在服务器端（如 Node.js 环境）没有 document 或 window 对象。如果直接在服务器端加载或使用 Cropper.js，会抛出类似 document is not defined 的错误。通过将代码放入 onMounted，确保它只在客户端的浏览器环境中运行，规避了服务器端的问题。

### 2. 动态导入 import("cropperjs")

- **动态导入的机制**：`await import("cropperjs")` 是一种动态导入方式，返回一个 Promise，仅在运行时加载指定的模块。与传统的静态导入（如 `import Cropper from 'cropperjs'`）不同，动态导入不会在代码加载时立即引入模块，而是推迟到代码执行时。
   
- 在 SSR 中的行为：

  - 在服务器端渲染阶段，Nuxt 3（或其他 SSR 框架）不会执行 `onMounted` 内的代码，因此动态导入不会触发。
  - 在客户端接管页面后，`onMounted` 触发，动态导入才开始执行，加载 Cropper.js。
  - 此外，动态导入的模块通常会被打包成单独的 chunk，仅在客户端需要时按需加载，避免服务器端接触到这些代码。
  
- **为什么能解决问题**：通过动态导入，`Cropper.js` 的加载被推迟到客户端环境，确保服务器端渲染时不会尝试解析或执行依赖 DOM 的代码，从而避免错误。

### 3. 类型安全与 import type

- **import type 的作用**：`import type { ... } from 'cropperjs'` 只导入 Cropper.js 的类型定义，用于 `TypeScript `的类型检查。这种导入不会引入实际的模块代码，仅在编译时生效。
- **为什么重要**：在服务器端渲染时，静态导入（如 import Cropper from 'cropperjs'）会尝试加载整个模块，导致错误。而 import type 避免了运行时加载模块，保证了服务器端的安全性，同时保留了 TypeScript 的类型支持。

------

## 为什么能解决 SSR 问题？

这段代码能解决 SSR 问题的根本原因在于以下几点：

1. **服务器端不执行客户端逻辑**：SSR 框架（如 Nuxt 3）在服务器端渲染时，只处理初始 HTML 的生成，不执行 onMounted 钩子。因此，依赖 DOM 的 Cropper.js 代码不会在服务器端运行，避免了因缺少浏览器环境而抛出的错误。
2. **动态导入的隔离性**：`await import("cropperjs") `确保 Cropper.js 只在客户端加载。服务器端渲染时，Nuxt 不会将动态导入的模块包含在初始 JavaScript 包中，而是交给客户端按需加载。这种隔离性防止了服务器端接触到不兼容的代码。
3. **类型导入的无运行时影响**：使用 import type 仅引入类型信息，不会在服务器端或客户端引入 Cropper.js 的实际实现。这样既保持了代码的类型安全，又避免了 SSR 过程中的运行时错误。

------

## 对比静态导入的效果

为了更清楚地理解，我们可以对比静态导入和动态导入的区别：

- 静态导入（会导致问题）：

  ```ts
  `import Cropper from 'cropperjs';`
  ```

  - 在 SSR 中，服务器端会立即尝试加载 cropperjs 模块。
  - 由于 Cropper.js 依赖 DOM API，服务器端会抛出错误（如 document is not defined）。

- 动态导入（解决问题） ：

  ```ts
  onMounted(async () => {
    const Cropper = (await import("cropperjs")).default;
  });
  ```

  - 服务器端跳过 onMounted，不会加载 Cropper.js。
  - 客户端执行时，动态加载 Cropper.js，运行在浏览器环境中，没有问题。

------

## 代码优化建议

你的代码中存在冗余：

- const Cropper = (await import("cropperjs")).default; 已经加载并获取了 Cropper.js 的默认导出。
- 紧接着的 await import("cropperjs"); 是多余的，因为模块已被加载。

优化后的代码如下：

```ts
<script setup lang="ts">
import type { CropperCanvas, CropperViewer, CropperSelection, CropperImage } from 'cropperjs';

onMounted(async () => {
  const Cropper = (await import("cropperjs")).default;
  // 示例：初始化 Cropper
  const image = document.getElementById('image');
  if (image) {
    const cropper = new Cropper(image, { /* 配置项 */ });
  }
});
</script>
```

## 总结

这段代码通过以下方式解决 SSR 问题：

- **利用 onMounted**：将 Cropper.js 的加载和初始化限制在客户端执行，避开服务器端渲染。
- **动态导入 import("cropperjs")**：确保模块只在客户端加载，避免服务器端接触 DOM 相关代码。
- **类型安全**：使用 import type 提供类型支持，不影响运行时行为。

这种方法是处理 SSR 与客户端库（如 Cropper.js）兼容性的常见且有效策略，确保了服务器端渲染的稳定性，同时保证客户端功能的正常运行。