Vite+SSR环境下如何跳过脚本类型检查并修复运行报错

问题原因 #

这个报错核心是第三方脚本diagramming.js在SSR的Node环境中，访问了浏览器专属全局对象（如window/document），或者其依赖的对象在Node环境未初始化，导致ImageAlign所属的父对象为undefined。你之前尝试的exclude和// @ts-nocheck仅处理了TS类型检查，未解决运行时环境不兼容的问题。

可行修复方案 #

方案1：仅在浏览器环境动态加载第三方脚本 #

利用React的useEffect钩子，确保脚本只在客户端（浏览器）执行，避开SSR的Node环境：

import { useEffect } from 'react';

function DiagramComponent() {
  useEffect(() => {
    // 动态导入本地脚本
    import('./path/to/diagramming.js').then((module) => {
      const { ImageAlign } = module.default;
      // 执行依赖ImageAlign的逻辑
    });

    // 若为全局CDN脚本，可通过创建script标签加载
    // const script = document.createElement('script');
    // script.src = '/path/to/diagramming.js';
    // script.onload = () => {
    //   const ImageAlign = window.DiagramLib?.ImageAlign;
    //   // 后续操作
    // };
    // document.body.appendChild(script);
    // return () => document.body.removeChild(script);
  }, []);

  return <div id="diagram-container"></div>;
}

export default DiagramComponent;

方案2：在Vite配置中标记第三方脚本为SSR外部依赖 #

如果diagramming.js是第三方npm包或无需Vite打包的脚本，在vite.config.ts中配置让Node直接处理它，避免Vite打包时破坏其运行逻辑：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  ssr: {
    // 替换为实际的包名或脚本路径
    external: ['diagramming'],
  },
});

方案3：为Node环境Polyfill浏览器全局对象（备选） #

如果脚本必须在SSR阶段执行，可在SSR入口文件（如server.ts）顶部手动Polyfill浏览器对象：

// 用jsdom模拟浏览器环境
import { JSDOM } from 'jsdom';
const dom = new JSDOM('<!DOCTYPE html>');
globalThis.window = dom.window;
globalThis.document = dom.window.document;

// 若仅需基础对象，可简化为：
// globalThis.window = globalThis.window || {};

注意：该方案会增加SSR性能开销，且部分浏览器API无法完美模拟，仅作为兜底方案。

方案4：修正TS配置的排除规则 #

检查tsconfig.json的路径是否精准，确保脚本目录被正确排除，同时让tsconfig.node.json仅作用于Node端文件：

// tsconfig.json
{
  "compilerOptions": {
    // 你的现有配置
  },
  "exclude": [
    "node_modules",
    "src/third-party-scripts/**/*", // 替换为你的脚本实际目录
    "dist"
  ]
}

// tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts", "server.ts"] // 仅包含Node端执行的文件
}

方案5：修改第三方脚本的环境兼容逻辑 #

如果允许修改diagramming.js，在脚本开头添加环境判断，确保父对象存在：

// 在diagramming.js顶部添加
const globalScope = typeof window !== 'undefined' ? window : globalThis;
globalScope.DiagramLib = globalScope.DiagramLib || {};

// 确保ImageAlign所属对象已初始化
export const ImageAlign = globalScope.DiagramLib.ImageAlign || {};

内容的提问来源于stack exchange，提问作者CraZyDroiD