Theme Packaging

主题打包与上传

打包

在主题目录内执行打包命令：

cd my-theme
zip -r my-theme-1.0.0.zip \
  theme.json \
  theme.css \
  assets/ \
  frontend/ \
  signature.json

未用到条目可以从命令中删掉：没有静态资源时去掉 assets/，主题未签名时去掉 signature.json。

ZIP 结构

my-theme-1.0.0.zip
├── theme.json          # 必须
├── theme.css           # 必须
├── assets/             # 可选
├── frontend/           # 可选
│   ├── manifest.json
│   └── dist/
└── signature.json      # 可选

上传校验

上传 ZIP 时，内核执行以下校验：

规则	限制
最大文件数	128
单文件最大	1 MB
解压总大小	8 MB
禁止可执行文件	.js/.ts/.mjs/.cjs/.jsx/.tsx（frontend/dist/*.js 除外）
禁止隐藏文件	.git*、.htaccess
路径安全	禁止 ..、绝对路径
ID 格式	/^[a-z0-9_-]{1,64}$/
保留 ID	default 不可使用
CSS 校验	只允许 :root/.dark Token 声明
CSS 大小	≤64 KB

签名

主题签名与插件签名使用相同的 Ed25519 机制，详见插件打包与签名。

安装主题

管理后台：访问 /admin/themes，点击上传按钮选择 ZIP 文件。

API：

curl -X POST http://127.0.0.1:3001/admin/themes \
  -H "Authorization: Bearer <token>" \
  -F "file=@my-theme-1.0.0.zip"

激活主题

管理后台：/admin/themes → 点击激活。

API：

curl -X PATCH http://127.0.0.1:3001/admin/themes/my-theme \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"active":true}'

激活新主题时，旧主题自动取消激活。同一时刻只有一个主题为 active。

预览主题

预览不需要激活，不影响线上：

# 设置预览
curl -X POST http://127.0.0.1:3001/admin/themes/preview \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"themeId":"my-theme"}'

# 退出预览
curl -X DELETE http://127.0.0.1:3001/admin/themes/preview \
  -H "Authorization: Bearer <token>"

前端通过 GET /preview?theme=<id>&path=<path> 预览任意页面。

删除主题

curl -X DELETE http://127.0.0.1:3001/admin/themes/my-theme \
  -H "Authorization: Bearer <token>"

default 主题不可删除，当前激活的主题也不可删除（返回 400）。删除前需先激活另一个主题。