一、安装与启用

上传主题后提示「主题缺少 style.css」？

说明你上传的是源码包而非主题包。请确认选择的是官方提供的 Qi-theme.zip，解压后顶层目录名为 qi-theme 且内含 style.css 与 functions.php。参考《安装部署》的「方式一 / 方式二」。

启用主题后前台白屏或 500 错误？

• 多为 内存不足 或 PHP 版本过低：在 wp-config.php 加入 define('WP_MEMORY_LIMIT', '256M');，并将 PHP 升级到 7.4 以上（推荐 8.1+）。
• 临时开启 define('WP_DEBUG', true); 查看具体报错，定位到冲突插件或缺失扩展后处理。

主题不出现在「外观 → 主题」列表？

检查：① 主题目录名是否为 qi-theme（不是 qi-theme-1.0.0 之类）；② style.css 头部 Theme Name 字段存在；③ 目录权限为 755、文件 644。详见《安装部署》「常见安装问题排查」。

二、演示数据导入

导入演示会覆盖或清空我现有的内容吗？

导入到一半卡住或失败？

• 增大 PHP 内存与执行时间：WP_MEMORY_LIMIT 调到 256M，max_execution_time 设为 300 以上。
• 确认服务器开启 curl、zip、gd 等扩展。
• 网络超时可重试导入，已导入的部分不会重复冲突。

导入后图片显示为占位图？

演示媒体需从服务器拉取，若网络受限可能未完整下载。可重新执行一次导入，或到「媒体库」手动补全缺失图片。页面结构与文字不受影响。

三、区块与可视化构建器

区块在编辑器中灰显 / 无法添加？

通常是浏览器缓存或编辑器脚本未加载。请：① 强制刷新（Ctrl/Cmd + Shift + R）；② 确认主题与配套构建器插件均已启用；③ 关闭与该区块功能重叠的插件（如其它页面构建器）后重试。

在编辑器里改了内容，前台不生效？

• 先清空站点缓存与浏览器缓存（若用了缓存插件 / CDN）。
• 确认你修改的是「已发布」版本，而非仅保存草稿。
• 检查是否启用了子主题却未继承父主题样式（见《安装部署》「方式四」）。

如何复制 / 复用某个区块？

在编辑器中选中区块，点击工具栏的「复制」；跨页面复用可用「复制到剪贴板」后粘贴，或用构建器的「保存为可复用区块 / 模板」功能，一处修改全局同步。

区块间距、宽度、圆角怎么调？

多数区块在右侧「区块设置」面板提供间距、宽度（全宽 / 对齐版心）、圆角与配色选项；全局默认值由「外观 → 自定义」统一控制，区块级设置会覆盖全局。

四、ICO / SVG 图标库

支持上传哪些图标格式？

后台图标库支持 .ico 与 .svg 两种格式。.svg 为矢量图，放大不失真，推荐优先使用；位图（png/jpg）请先转成 svg 或 ico 再上传。

上传 SVG 后图标不显示 / 显示为空白？

• 确认 SVG 文件本身有效（用浏览器直接打开能渲染）。
• 部分主题会过滤 SVG 中的脚本，若含 <script> 会被移除导致空白，请使用纯矢量路径的 SVG。
• 需在「设置 → 媒体」或对应权限处允许 SVG 上传（主题通常已默认开启）。

图标怎么插入到文章或区块？

在图标库点击「复制短代码 / 调用代码」，粘贴到文章或「自定义 HTML」区块；部分区块提供「图标选择器」，可直接从库中点选插入，无需手写代码。

五、全局样式与定制

改了主色，但部分区块颜色没变？

区块若被单独设置了固定颜色，会覆盖全局主色。到该区块设置里把颜色改回「继承全局 / 默认」即可随全局联动。另外清缓存后查看更准。

字体设置没生效？

• 确认字体名称与「外观 → 自定义 → 字体」中一致，部分字体需先引入（主题字体库已内置常用字体）。
• 若用子主题自定义了字体，请用 wp_enqueue_style 正确引入字体文件，避免被父主题样式覆盖。

版心宽度、页眉页脚布局在哪调？

统一在「外观 → 自定义」中调整：包含站点身份（站名 / Logo / 站点图标）、配色、字体、版心宽度、页眉页脚布局等。修改会实时预览，满意后「发布」即可全站生效。

六、子主题与二次开发

更新父主题会丢失我的修改吗？

如何安全地做二次开发？

安装配套子主题（Template: qi-theme），在子主题 functions.php 中用 wp_enqueue_* 引入自定义资源，模板文件放到子主题同名覆盖。参考《安装部署》「方式四：子主题安装」。

七、更新与升级

如何升级到新版本？

1. 备份数据库与 wp-content（尤其未使用子主题时）。
2. 若用子主题：直接覆盖更新父主题 qi-theme/ 目录即可。
3. 若未用子主题：停用后重新上传新版 Qi-theme.zip，再到后台启用；你的内容与设置在数据库中不受影响。

升级后页面报错 / 样式错乱？

先清空所有缓存（插件、CDN、浏览器）；再检查是否有旧版自定义代码与新版不兼容。若问题依旧，开启 WP_DEBUG 定位，或临时切回默认主题对比排查。

八、性能与 SEO

页面加载偏慢怎么办？

• 启用缓存插件（如 WP Super Cache / Redis），并开启 CDN 加速静态资源。
• 压缩上传的图片，优先使用 WebP；图标用 SVG 矢量。
• 主题本身轻量、无冗余依赖，多数卡顿来自第三方插件或未压缩媒体。

SEO 相关要怎么设置？

主题输出语义化结构与标准标签，利于搜索引擎抓取。建议配合 SEO 插件（如 Rank Math / Yoast）设置标题、描述与站点地图；在「设置 → 阅读」中确认未勾选「建议搜索引擎不索引本站点」。

九、兼容性与故障排查

和某些插件冲突 / 功能异常？

1. 进入「插件」，逐个停用第三方插件，刷新页面定位冲突源。
2. 用默认主题（如 Twenty Twenty-Four）测试，判断是否为主题本身问题。
3. 确认冲突插件为最新版，必要时联系其作者或改用同类插件。

最低环境要求是多少？

WordPress 6.0 起、PHP 7.4 起（推荐 8.1+）、MySQL 5.6 / MariaDB 10.0 起。完整要求见《安装部署》「环境要求」表。

如何开启调试模式查看报错？

在 wp-config.php 设置 define('WP_DEBUG', true); 与 define('WP_DEBUG_LOG', true);，报错会写入 wp-content/debug.log，方便定位问题后提交给支持方。