Skip to content

Troubleshooting zh CN

Jump to bottom
老王杂谈说 edited this page Jul 21, 2026 · 1 revision

🇨🇳 中文 | 🇺🇸 English

Home · Store · Changelog

故障排除

使用 Skins Pro 时的常见问题及解决方案。

⚠️ 第一步：清除缓存

每当你看到布局错乱、图标缺失或奇怪的视觉故障时 — 始终从这里开始。

  1. 强制刷新： Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（Mac）
  2. 清除浏览器缓存： Chrome → 设置 → 隐私与安全 → 清除浏览数据 → 缓存的图片和文件 → 时间不限
  3. 重启 HA Companion App（移动端用户）
  4. 尝试无痕/隐私模式 — 如果在该模式下正常，则说明是缓存问题

缓存问题是"布局错乱"报告的头号原因。Skins Pro 通过浏览器和 HA 的前端缓存积极缓存 CSS 和 JS。强制刷新可解决 90% 的视觉问题。

症状： 仪表盘显示空白卡片，或皮肤样式/图片未显示。

解决方案：

  1. 强制刷新 — 按 Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（Mac）绕过浏览器缓存。

  2. 检查资源 — 前往设置 → 仪表盘 → 资源，确认：

    • /local/skins-pro.js（或 /local/community/skins-pro/skins-pro.js）已列出
    • 类型设置为 JavaScript Module

  3. 检查 HACS 安装 — 如果通过 HACS 安装，请确保自定义仓库 URL 正确：https://github.com/ha-china/Skins-Pro

  4. 浏览器控制台 — 打开开发者工具（F12）→ 控制台选项卡。查找：

    • skins-pro.js 的 404 错误 — 文件不在预期 URL 上
    • theme.css 的 404 错误 — 皮肤资源未部署
    • Lit 错误 — 可能存在版本不匹配

  5. Modern 皮肤未加载 — 如果内置的 modern 皮肤图片/样式缺失，请将 dist/modern/ 复制到你的 HA www/ 文件夹：

    <HA 配置>/www/community/skins-pro/modern/

图标不显示

症状： 环境传感器图标为空白，或天气图标缺失。

解决方案：

  1. 强制刷新 — 首先清除浏览器缓存。

  2. 检查实体状态 — 前往 HA 中的开发者工具 → 状态，确认实体具有：

    • attributes.icon — 用户设置或集成设置的图标
    • device_class — 用于默认图标解析（例如 humidity → mdi:water-percent）

  3. HA 图标解析 — Skins Pro 使用 HA 原生的 <ha-state-icon> 组件。如果图标在 HA 标准 UI 中显示但在 Skins Pro 中不显示，很可能是 HA 前端版本问题。

  4. 天气图标 — 天气图标也通过 <ha-state-icon> 解析。如果主要天气图标正常但预报图标不显示，请检查你的 HA 版本（需要 2024+）。

卡片编辑器无法打开

症状： 点击卡片未显示编辑器，或编辑器为空白。

解决方案：

  1. 检查权限 — 确保你以管理员用户身份登录。

  2. 浏览器控制台错误 — 查找可能阻止编辑器渲染的 JavaScript 错误。

  3. 重新添加卡片 — 从仪表盘中移除卡片并重新添加。

皮肤商店下载失败

症状： 在皮肤商店中点击"下载"无效，或下载从未完成。

解决方案：

  1. 安装集成 — 皮肤商店需要 skins-pro-hass 集成。从 HACS 安装或手动复制到你的 custom_components/ 文件夹。

  2. 检查网络 — 皮肤商店从 CDN 获取数据。确保你的 HA 实例具有互联网访问权限。

  3. 手动安装 — 如果商店无法使用，你可以手动下载皮肤并将其放置在：

    <HA 配置>/www/skins-pro/<皮肤名称>/

    然后在卡片编辑器中将该皮肤名称添加到 downloaded_skins。

构建错误

症状： npm run build 失败并显示错误。

解决方案：

  1. 检查 Node.js 版本 — 需要 Node.js 18+。

  2. 重新安装依赖：

    rm -rf node_modules
npm install

  3. TypeScript 错误 — 运行 npm run type-check 查看具体的类型错误。

  4. 图片处理错误 — 确保图片是有效的 PNG/JPG/BMP/WebP 文件。损坏的图片会导致 sharp 处理失败。

Kiosk 模式问题

症状： Kiosk 模式未激活，或非管理员用户可以退出 Kiosk。

解决方案：

  1. 管理员用户 — 点击头像可切换 Kiosk。如果无效，请检查卡片编辑器中是否启用了 fullscreen。

  2. 非管理员用户 — Kiosk 被强制启用。如果非管理员用户可以退出，请确保 hass.user.is_admin 正确报告用户角色。

  3. 右键菜单仍然可用 — 右键菜单阻止器仅阻止卡片上的上下文菜单。如果右键菜单在 HA 侧边栏上仍然可用，这是预期的行为 — 阻止器仅适用于仪表盘区域。

性能缓慢

症状： 仪表盘加载缓慢或切换视图时卡顿。

解决方案：

  1. 减少设备数量 — 在卡片编辑器中按区域或类型筛选设备。

  2. 限制环境传感器数量 — 在编辑器中设置 home_limits.environment 以限制显示的传感器数量。

  3. 摄像头快照 — 每次仪表盘渲染时摄像头快照都会更新。如果导致卡顿，考虑在首页禁用摄像头。

  4. 浏览器硬件加速 — 在浏览器设置中启用硬件加速。

报告问题

如果以上故障排除步骤未能解决，请提交 issue 并提供：

  • 你的 HA 版本
  • 浏览器及版本
  • Skins Pro 版本
  • 重现步骤
  • 截图或控制台日志（如适用）

Clone this wiki locally