前言
在开发 SonicToolLab 的过程中，我遇到了一个让独立开发者非常头疼的问题：部署失败。
当我引入了 jspdf (生成 PDF)、xlsx (处理 Excel) 和 @faker-js/faker (生成模拟数据) 后，Cloudflare Pages 部署时直接报错：
Error: Script startup exceeded CPU time limit或Worker bundle size exceeded 1MB limit
这是因为 Nuxt 是同构框架。虽然我们心里清楚：“这些库只在浏览器里用，服务器不需要运行”，但在构建时，Nitro 引擎可能会因为某些静态导入（Static Import），把这些几百 KB 的巨型库打包进了 server/index.mjs。
今天分享一个终极解决方案：利用 Nitro 的 alias 配置，通过“偷梁换柱”的方式，让这些库在服务端彻底消失。
🚨 1. 问题复现：为什么服务端包会变大？
假设你有一个工具页 pages/pdf-tool.vue：
// 即使你在 setup 中没调用，静态导入也可能导致打包工具将其分析为服务端依赖
import { jsPDF } from "jspdf";
const generate = () => {
const doc = new jsPDF();
doc.save("test.pdf");
}
当你运行 pnpm build 后，检查 .output/server/index.mjs，你会惊讶地发现 jspdf 的源码竟然被完整打包进去了！
对于 Cloudflare 这种 Serverless 环境，每一 KB 都是宝贵的。这些无用的代码不仅占空间，还会拖慢 Cold Start（冷启动）速度。
✂️ 2. 终极一刀：Nitro Alias 替换法
我们不能简单地依赖 Tree-shaking，最稳妥的方法是告诉 Nitro 打包器： “当你在服务端遇到这些库时，用一个空文件替换它。”
第一步：创建一个 Mock 文件
在 server/utils 下创建一个简单的 mock.ts。它的作用是提供一个空的导出，防止服务端运行时因为“找不到模块”而报错。
TypeScript
// server/utils/mock.ts
// 导出一个 Proxy，这样无论代码尝试访问什么属性都不会报错，只会返回 undefined
export default new Proxy({}, {
get: () => () => {}, // 所有方法都返回空函数
});
第二步：配置 nuxt.config.ts
这是核心操作。利用 nitro.alias 将那些纯客户端的巨型库映射到上面的 Mock 文件。
TypeScript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
// 🔥 核心配置：使用别名在服务端将这些库替换为空模块
// 彻底从 Server Worker 中剔除，防止体积超标
alias: {
"@faker-js/faker": "./server/utils/mock.ts",
"jspdf": "./server/utils/mock.ts",
"pdfjs-dist": "./server/utils/mock.ts",
"upng-js": "./server/utils/mock.ts",
"jszip": "./server/utils/mock.ts",
// 其他只需要在浏览器运行的大型库都可以在这里加
}
}
})
原理说明：
当 Nitro 构建服务端 Bundle 时，一旦看到 import ... from 'jspdf'，它不再去 node_modules 里找几百 KB 的源码，而是直接引用了只有几行代码的 ./server/utils/mock.ts。
注意： 这不会影响客户端（Client Bundle）。浏览器端依然会正常加载完整的库。
📦 3. 配合动态导入 (Dynamic Import)
除了配置 Alias，我们在写代码时也应该尽量避免在 <script setup> 顶层直接 import 巨型库。
优化前的写法（容易导致 Hydration 问题）：
TypeScript
import JSZip from 'jszip' // ❌ 可能会影响首屏加载
优化后的写法：
TypeScript
const handleDownload = async () => {
// ✅ 只有当用户点击按钮时，浏览器才去加载 JSZip
const { default: JSZip } = await import('jszip')
const zip = new JSZip()
// ...
}
结合 nitro.alias + await import()，你的工具站将达到体积优化的巅峰。
📊 4. 效果对比
在 SonicToolLab 应用该策略前后，.output/server/index.mjs 的体积变化惊人：
- 优化前： 2.4 MB (Cloudflare 无法部署)
- 优化后： 480 KB (秒部署，且冷启动极快)
特别是 @faker-js/faker 这种包含大量文本数据的库，一旦剔除，减重效果立竿见影。
⚠️ 5. 避坑指南
虽然 Alias 很好用，但有一个绝对前提：
你的服务端代码（API 接口、SSR 渲染逻辑）绝对不能真正使用这些库。
如果你在 server/api/generate-pdf.ts 里确实需要用到 jspdf 来生成文件，那你不能把它 Mock 掉。
本方案仅适用于：
库只在浏览器（Vue 组件）中使用，但因为构建工具的机制被误打包进服务端的场景。
总结
Cloudflare Pages 虽然免费且强大，但资源限制是硬伤。对于 Nuxt 开发者来说，学会管理服务端依赖是一门必修课。
通过简单的 mock.ts 和 nitro.alias 配置，我们成功给服务端“抽脂”，让 SonicToolLab 在边缘节点上跑得飞快。
