furniture-3d-system-Wu/docs/troubleshooting-theme.md

主题不适配问题排查指南

问题现象

按钮显示为固定的蓝色（#007AFF），不随主题切换而改变。

可能的原因

1. 浏览器缓存问题 ⭐ 最常见

浏览器可能缓存了旧的 CSS 文件。

解决方案：

1. 硬刷新页面：

   • Windows: Ctrl + Shift + R 或 Ctrl + F5
   • Mac: Cmd + Shift + R

2. 清除浏览器缓存：

   • Chrome: 设置 → 隐私和安全 → 清除浏览数据 → 选择"缓存的图片和文件"
   • 或者使用无痕模式测试

3. 重启开发服务器：

   # 停止服务器 (Ctrl+C)
   # 删除 .next 文件夹
   rm -rf .next
   # 重新启动
   npm run dev
   

2. data-theme 属性未设置

检查方法： 打开浏览器开发者工具（F12），在 Console 中运行：

console.log(document.documentElement.getAttribute('data-theme'))

预期结果：应该输出 "light" 或 "dark"

如果输出 null：

• 检查 src/app/layout.tsx 中 <html> 标签是否有 data-theme="light" 属性
• 检查浏览器 Console 是否有 JavaScript 错误

3. CSS 变量未定义

检查方法：

console.log(getComputedStyle(document.documentElement).getPropertyValue('--color-blue'))

预期结果：

• 浅色模式：#007AFF 或 rgb(0, 122, 255)
• 深色模式：#0A84FF 或 rgb(10, 132, 255)

如果输出为空：

• 检查 src/app/globals.css 是否正确导入
• 检查 CSS 变量定义是否正确

4. Tailwind 类名未生成

检查方法：

const button = document.querySelector('.bg-apple-blue')
console.log(getComputedStyle(button).backgroundColor)

预期结果：应该输出 RGB 颜色值

如果输出 rgba(0, 0, 0, 0) 或透明：

• Tailwind 可能没有生成 bg-apple-blue 类
• 检查 tailwind.config.ts 中是否定义了 apple-blue 颜色
• 重新构建项目

完整诊断脚本

在浏览器 Console 中运行以下脚本：

console.log('=== 主题系统完整诊断 ===\n')

// 1. 检查 data-theme
const theme = document.documentElement.getAttribute('data-theme')
console.log('1. data-theme 属性:', theme)
if (!theme) {
  console.error('❌ 错误: data-theme 属性未设置！')
} else {
  console.log('✓ data-theme 已设置')
}

// 2. 检查 CSS 变量
const colorBlue = getComputedStyle(document.documentElement).getPropertyValue('--color-blue')
console.log('\n2. CSS 变量 --color-blue:', colorBlue)
if (!colorBlue || colorBlue.trim() === '') {
  console.error('❌ 错误: CSS 变量未定义！')
} else {
  console.log('✓ CSS 变量已定义')
  console.log('  浅色模式应该是: #007AFF')
  console.log('  深色模式应该是: #0A84FF')
}

// 3. 检查按钮
const button = document.querySelector('.bg-apple-blue')
if (!button) {
  console.warn('⚠ 警告: 页面上没有找到 .bg-apple-blue 的元素')
} else {
  const buttonBg = getComputedStyle(button).backgroundColor
  console.log('\n3. 按钮背景色:', buttonBg)
  if (buttonBg === 'rgba(0, 0, 0, 0)' || buttonBg === 'transparent') {
    console.error('❌ 错误: 按钮背景色为透明！Tailwind 类可能未生成')
  } else {
    console.log('✓ 按钮有背景色')
  }
}

// 4. 检查 Tailwind 配置
console.log('\n4. 检查 Tailwind 类名')
const testDiv = document.createElement('div')
testDiv.className = 'bg-apple-blue'
document.body.appendChild(testDiv)
const testBg = getComputedStyle(testDiv).backgroundColor
document.body.removeChild(testDiv)
console.log('  测试元素背景色:', testBg)
if (testBg === 'rgba(0, 0, 0, 0)') {
  console.error('❌ 错误: bg-apple-blue 类未生成或未应用')
} else {
  console.log('✓ Tailwind 类正常工作')
}

// 5. 检查 localStorage
const savedTheme = localStorage.getItem('apple-ui-theme')
console.log('\n5. localStorage 中保存的主题:', savedTheme || '未设置')

console.log('\n=== 诊断完成 ===')

使用调试页面

访问 http://localhost:3000/debug-theme 查看详细的主题信息和测试按钮。

快速修复步骤

步骤 1: 清除缓存

# 停止开发服务器
# 删除构建缓存
rm -rf .next

# Windows PowerShell:
Remove-Item -Recurse -Force .next

# 重启服务器
npm run dev

步骤 2: 硬刷新浏览器

• Windows: Ctrl + Shift + R
• Mac: Cmd + Shift + R

步骤 3: 检查 HTML

打开开发者工具 → Elements 标签 → 查看 <html> 标签：

<html lang="zh-CN" data-theme="light">

步骤 4: 测试主题切换

1. 点击页面右上角的主题切换按钮
2. 观察按钮颜色是否改变
3. 检查 Console 中的输出

预期行为

浅色模式

• data-theme="light"
• 按钮背景：亮蓝色 (#007AFF)
• 页面背景：白色/浅灰色
• 文字：黑色/深灰色

深色模式

• data-theme="dark"
• 按钮背景：更亮的蓝色 (#0A84FF)
• 页面背景：黑色/深灰色
• 文字：白色/浅灰色

如果问题仍然存在

1. 检查浏览器 Console 是否有错误
2. 访问 /debug-theme 页面查看详细信息
3. 运行完整诊断脚本
4. 检查 src/app/layout.tsx 中的内联脚本是否正确执行
5. 尝试在无痕模式下打开页面

常见错误信息

"主题初始化失败"

• 内联脚本执行出错
• 检查浏览器是否支持 localStorage
• 检查是否在隐私模式下

CSS 变量为空

• globals.css 未正确加载
• CSS 变量定义有语法错误
• Tailwind 配置问题

按钮背景色为透明

• Tailwind 未生成 bg-apple-blue 类
• 检查 tailwind.config.ts 配置
• 重新构建项目

联系支持

如果以上方法都无法解决问题，请提供：

1. 浏览器类型和版本
2. 完整诊断脚本的输出
3. 浏览器 Console 中的错误信息
4. /debug-theme 页面的截图