跳转到内容
BangNiCMS 文档

安装与切换主题

主题的安装和切换全部在后台「扩展市场」操作——零命令行、零代码。

后台入口：扩展市场 → 主题 Tab

主题的状态

Section titled “主题的状态”

每个主题有几种状态：

  • 可用 — 已上传但未启用
  • 已启用（active）— 当前生效，前台用这个主题渲染
  • 已停用（disabled）— 装了但没启用
  • 内置 — 系统自带，永久存在
待补充截图 每个主题卡片右上角徽章：「已启用」「已停用」「内置」之一
主题列表卡片显示状态

上传第三方主题

Section titled “上传第三方主题”

  1. 从可信渠道获取主题 .zip 包：

    • BangNiCMS 官方
    • 经过官方认证的开发者
    • 公司内部开发团队

  2. 进「扩展市场 → 主题」 → 点右上角 上传主题

  3. 拖拽 / 选择 .zip 文件

    待补充截图 拖拽区域 + 文件选择按钮 + 上传后实时校验进度
    上传主题弹窗

  4. 系统自动校验：

    • 文件结构是否合法（必须有 manifest.json）
    • 必填字段（名称、版本、类型）是否齐全
    • 类型必须是 theme（不是 plugin）
    • 唯一键格式是否合法

  5. 校验通过 → 主题状态自动设为「已停用」（不会自动启用）

  6. 激活：在主题卡片点 启用 → 替换当前主题

激活（切换）主题

Section titled “激活（切换）主题”

激活新主题 = 同时停用之前的 active 主题。系统在一次操作里原子完成。

  1. 在主题列表找到目标主题

  2. 点 启用 按钮

  3. 弹窗确认：

    ⚠️ 即将切换主题：
    当前：内置主题
    切换到：现代企业站 v2.1
    

    切换后前台立即生效，建议先验证关键页面：
    ✓ 首页
    ✓ 产品详情页
    ✓ 文章详情页
    ✓ 联系我们
    

    [取消] [确认切换]

  4. 确认 → 切换完成，前台立即用新主题渲染

待补充截图 弹窗显示切换前后对比 + 提示验证哪些关键页 + 取消 / 确认按钮
切换主题确认弹窗

切换后立即验证

Section titled “切换后立即验证”

切换成功后第一件事：打开前台测试关键页面

检查项怎么看
首页正常加载没有空白、没有大段错位
Header / Footer 完整Logo、菜单、联系信息都在
产品详情页布局正常封面、详情、相关产品都显示
文章详情页正常正文、图片、相关文章
联系我们 / 询盘表单表单可提交
多语言切换正常切换语言 URL 正确

发现问题：

  • 立刻切回内置主题（兜底）
  • 联系主题开发者修复
  • 别让用户看到坏掉的页面

卸载第三方主题

Section titled “卸载第三方主题”
报错提示怎么解决
当前启用的主题不能卸载先切换到其他主题（如内置主题），再卸载
系统内置扩展不可卸载内置主题不能卸载——这是设计上的保护

  1. 把要卸载的主题先切换走（激活其他主题）

  2. 状态变 已停用 → 卡片出现 卸载 按钮

  3. 点 卸载 → 弹窗确认 → 确认

  4. 主题文件从服务器删除，数据库记录也删除

升级主题（新版本）

Section titled “升级主题（新版本）”

主题开发者发了新版本，怎么升级？

  1. 拿到新版 .zip 包

  2. 进「扩展市场 → 主题」 → 点 上传主题

  3. 上传同 extensionKey 的新版 zip → 系统检测到已有同名主题 → 弹窗确认

  4. 确认升级：

    • 旧版本被覆盖（主题代码替换）
    • 状态保持不变（如果旧版是 active，新版仍是 active）
    • 运营在主题里的设置内容：取决于开发者是否做了”配置兼容”——通常保留，但可能需要按新版手册调整

  5. 升级后立刻验证关键页面

一些边界情况

Section titled “一些边界情况”

装的 zip 校验失败

Section titled “装的 zip 校验失败”
报错原因解决
不是合法的 zip 文件文件损坏让开发者重新打包
缺少 manifest.json包结构不对让开发者按规范打包（详见主题开发文档）
manifest.json 缺少必填字段开发者漏填让开发者补
extensionType 必须是 theme错装成插件了选对应的 plugin 上传入口
唯一键格式不合法包含中文 / 大写 / 特殊字符让开发者改成英文小写 + 连字符

主题 zip 太大上传失败

Section titled “主题 zip 太大上传失败”

通常发生在 zip > 100 MB 时。原因：

  • 主题包里塞了大量设计稿 / 高清图（应该放线上 CDN 而不是包内）
  • 包含未压缩的视频
  • 没排除 node_modules（开发者疏忽）

让开发者精简：

  • 设计稿放外部
  • 图片转 WebP / 用 CDN
  • 排除开发依赖

装上后前台白屏

Section titled “装上后前台白屏”

最快恢复：进后台立刻切回内置主题。

如果后台也进不去（极少见），让运维：

UPDATE extension SET status = 'disabled'
WHERE extension_type = 'theme' AND is_builtin = false;

详见 故障排查 章节（建设中）。

常见问题

Section titled “常见问题”

切换主题后我之前做的颜色设置还在吗？

Section titled “切换主题后我之前做的颜色设置还在吗？”

通常不在——主题设置（如颜色、字体）通常与主题绑定。切换主题 = 启用新主题的默认设置。

切换前截图保存当前主题设置，新主题装好后对照恢复。

我能装多个第三方主题但只启用一个吗？

Section titled “我能装多个第三方主题但只启用一个吗？”

可以——上传后默认就是「已停用」状态。你可以装 5 个主题但只启用一个。

用途：

  • 季节性切换（圣诞主题、春节主题）
  • A/B 测试备选
  • 临时活动（双十一专题主题）

我能定时切换主题吗（如每年圣诞自动切换）？

Section titled “我能定时切换主题吗（如每年圣诞自动切换）？”

当前不支持自动定时切换——需要运营手动切。

如果你需要这个能力，让开发者写一个”定时任务插件”。

主题升级后，我的内容会变吗？

Section titled “主题升级后，我的内容会变吗？”

不会——主题只决定怎么展示，不动内容。

但首页的某些区块 ↑可能因为主题升级而显示位置 / 样式变化——这是正常的。如果开发者在升级里调整了首页结构，你需要按新版手册重新检查。

测试环境怎么搭？

Section titled “测试环境怎么搭？”

最简单：在另一台服务器（或同一服务器的不同端口）部署一份 BangNiCMS。用同一份数据库还原到测试环境，新主题先装到测试环境验证再上生产。

详见 备份与升级 章节（建设中）。

接下来

Section titled “接下来”