NextJS+TypeScript+Stitches中styled组件遇TS(4118)序列化错误求助

错误原因 #

这个报错是Next.js SSR的序列化机制导致的——你用自定义Stitches config生成的styled组件，内部带有[$$PropertyValue]属性，其中包含了函数或非JSON兼容的类型，Next.js在将服务端渲染的组件数据传递到客户端时，无法序列化这些内容，因此抛出TS4118错误。而直接用@stitches/react默认导出的styled，其内部类型经过官方处理，不会携带这类无法序列化的属性。

解决办法 #

1. 规范Stitches config的导出方式 #

不要在组件文件内临时定义config，单独创建stitches.config.ts文件，用标准方式导出styled：

// stitches.config.ts
import { createStitches } from '@stitches/react';

export const { styled, css, theme } = createStitches({
  // 自定义配置示例：主题色、媒体查询等
  theme: {
    colors: {
      primary: '#0070f3',
    },
    media: {
      md: '(min-width: 768px)',
    },
  },
});

确保该config为顶层模块，不会在组件渲染时动态创建，避免每次渲染生成新的styled实例导致类型混乱。

2. 临时禁用特定组件的SSR（不推荐长期使用） #

如果个别组件暂时无法解决序列化问题，可使用Next.js的dynamic导入关闭SSR：

import dynamic from 'next/dynamic';

// 导入目标styled组件并禁用SSR
const MyStyledButton = dynamic(() => import('../components/MyStyledButton'), {
  ssr: false,
});

此方法会丢失SSR的优势，仅适合临时救急。

3. 升级Stitches到最新稳定版 #

部分旧版本的Stitches在SSR与TS类型兼容上存在bug，升级到@stitches/react@1.2.8及以上的稳定版，大概率能自动修复该序列化问题。

4. 调整TypeScript配置（辅助手段） #

检查tsconfig.json中的strict相关配置，可暂时调整strictNullChecks或strictFunctionTypes的严苛程度，但这仅为辅助手段，核心解决方式仍为前面的config导出规范与版本升级。

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