常见问题

本页汇总 React + Tailwind + TypeScript 模板开发中最高频的问题，每个问题都给出症状、原因和完整解决方案。

依赖安装失败

症状

pnpm install
# ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

或者 npm install 报 ERESOLVE unable to resolve dependency tree。

原因

React 版本冲突或 peer dependencies 不匹配。@karinjs/template-react 的 peer 要求是 react >=18.0.0（react-dom 同），脚手架默认安装 React 19（^19.2.8）。如果项目里已有 React 17 或更旧版本、或其他包锁定了不兼容的版本，包管理器拒绝安装。

解决方案

1. 检查现有 React 版本

pnpm list react react-dom

如果版本低于 18.0，先升级。建议与脚手架口径一致，直接装 React 19：

{
  "devDependencies": {
    "react": "^19.2.8",
    "react-dom": "^19.2.8"
  }
}

2. 清理缓存重装

rm -rf node_modules pnpm-lock.yaml
pnpm install

3. pnpm 用户：允许 peer 警告

pnpm install --no-strict-peer-dependencies

或在 .npmrc 里永久设置：

strict-peer-dependencies=false

类型不生效

症状

renderImage 的路由和 data 参数失去类型提示，或 VSCode 报 Cannot find module '@karinjs/template-react/registry-types'。

原因

.ktr/registry-types.d.ts 未生成或 TypeScript 编译器未加载模块增强声明。

解决方案

1. 执行 sync 生成类型文件

pnpm ktr sync

成功后 .ktr/ 目录应该有三个文件：

.ktr/
├── template-registry.ts
├── mock-registry.ts
└── registry-types.d.ts  ← 类型增强声明

2. 重启 TypeScript 服务器

VSCode 按 Ctrl+Shift+P（macOS Cmd+Shift+P），运行 TypeScript: Restart TS Server。

3. 检查 tsconfig.json

确保 .ktr/ 没有被 exclude 排除：

// @errors: 18046
{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src", "ktr", ".ktr"],
  "exclude": ["node_modules", "lib"]
}

完整排查见 类型问题详解。

样式不生效

症状

开发面板或真实渲染的截图里，所有 Tailwind 类名（如 bg-background、text-foreground）都不生效，元素呈现浏览器默认样式。

原因

ktr/template/style.css 缺失、入口路径配置错误、或 Tailwind 扫描路径不包含模板目录。

解决方案

1. 检查 CSS 入口文件

确保 ktr/template/style.css 存在且内容正确：

@import 'tailwindcss';
@import '@karinjs/template-react/styles';
@source './**/*.{ts,tsx}';

缺失时手动创建，或重新执行 pnpm ktr init 选择生成。

2. 验证扫描路径

@source './**/*.{ts,tsx}' 告诉 Tailwind 扫描 ktr/template/ 下的所有 .ts 和 .tsx 文件。如果模板放在别的目录，调整为相对 style.css 的路径。

3. 清理 Vite 缓存

rm -rf node_modules/.vite
pnpm ktr dev

4. 检查主题覆盖

如果自己写了 @theme { ... } 块，删掉改用变量覆盖：

@import 'tailwindcss';
@import '@karinjs/template-react/styles';
@source './**/*.{ts,tsx}';

/* ✅ 正确：覆盖变量 */
:root {
  --accent: oklch(0.62 0.19 254);
}

/* ❌ 错误：会盖掉 HeroUI 的 @theme inline */
/* @theme { --color-accent: var(--accent); } */

热更新不工作

症状

修改模板组件或 data/*.json 保存后，开发面板预览没有自动刷新，必须手动刷新浏览器。

原因

Vite HMR 连接断开、WebSocket 被代理或防火墙阻断、或文件监听失败。

解决方案

1. 检查控制台错误

浏览器 DevTools Console 里看是否有 WebSocket 连接失败：

[vite] failed to connect to websocket.
[vite] WebSocket connection to 'ws://localhost:5180/' failed

2. 代理场景配置 WebSocket

如果通过 Nginx 或其他代理访问面板，确保代理转发 WebSocket：

location / {
  proxy_pass http://localhost:5180;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

3. WSL / 虚拟机场景

Vite 默认用 localhost，WSL 或虚拟机里可能监听不到宿主机访问。改为监听所有接口：

export default defineConfig({
  dev: {
    host: '0.0.0.0',
    port: 5180
  }
})

4. 文件系统监听问题

某些 Linux 发行版默认的 inotify 限制太低：

# 临时提升
sudo sysctl fs.inotify.max_user_watches=524288

# 永久生效
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

构建失败

症状

vite build
# Error: Cannot find module '.ktr/template-registry'

或者构建成功但产物目录（如 lib/）缺少 style.css。

原因

打包配置未挂 ktrBuildPlugin()，或注册表入口未加到 build.lib.entry。

解决方案

1. 检查 Vite 配置

确保 vite.config.ts 包含以下关键配置：

import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { ktrBuildPlugin } from '@karinjs/template-react/plugin'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    ktrBuildPlugin() // ← buildStart 自动 sync，generateBundle 编译 CSS 并注入 bundle
  ],
  ssr: {
    noExternal: true,
    external: ['node-karin']
  },
  build: {
    ssr: true,
    target: 'node18',
    outDir: 'lib',
    lib: {
      entry: {
        'apps/template': 'src/apps/template.ts',
        // ↓ 生产渲染器需要模板注册表
        'template-registry': '.ktr/template-registry.ts'
      },
      formats: ['es']
    },
    rollupOptions: {
      external: [/^node:/, 'node-karin']
    }
  }
})

2. 手动执行 sync

ktrBuildPlugin 会在 buildStart 自动同步，但如果插件加载失败，手动跑一次：

pnpm ktr sync
vite build

3. 验证产物

构建成功后 lib/ 应包含：

lib/
├── apps/
│   └── template.js
├── template-registry.js
└── style.css  ← CSS 编译产物

缺少 style.css 时检查 ktrBuildPlugin 是否在插件列表里、是否传了 { css: false }。

完整排查见 构建问题详解。

下一步