安装包规范与打包
上传到应用市场的模板包与源码（插件）包，都会在报名表提交前先经
Core\PackageValidator 规范检测。本文把检测项、必填文件、打包方式与
常见驳回原因一次讲清——照着本文打包，可以一次通过。
一、检测结果的三档
检测返回四类信息：
| 档位 | 字段 | 是否阻断 | 说明 |
|---|---|---|---|
| 错误 | errors | 是 | 存在任一项即不允许上传 / 不通过 |
| 建议 | warnings | 否 | 仅提示，不阻断，但建议补齐 |
| 元信息 | info | — | 从包内描述文件解析出的 name/title/version/author |
| 文件数 | files | — | 包内有效文件数量（已过滤 macOS 元数据） |
后台「规范检测」与前台发布表单共用同一套校验，口径完全一致。
二、通用检测（两类包都做）
- 不是有效 zip → 报错。文件不存在、损坏、或服务器未启用
zip扩展都会拦截。
- 压缩包为空 → 报错。
- 目录穿越 / 绝对路径 → 报错。包内出现
../、以/开头、
或以盘符（如 C:）开头的条目，一律拒绝。
- 公共顶层目录自动去除 —— 如果包内所有文件都在同一个顶层目录下
（例如 my-theme/…），校验时会剥掉这层前缀，使包根规范化。
两种打包方式都接受：直接压内容，或压一层文件夹。
- 危险函数扫描 —— 对包内
.php/.inc/.phtml文件扫描
eval / assert / system / exec / shell_exec / passthru / popen / proc_open，
命中会写入 warnings（提示确认安全，不阻断）。
- 介绍文件检测 —— 包内需有
README.md/README.txt/README
或 docs/ 目录下的说明文件，否则给出「建议补充介绍文件」的建议项。
- macOS 元数据自动忽略 ——
__MACOSX/与.DS_Store会被跳过，不影响检测。
三、模板包（type = template）
必需（errors）
| 文件 / 字段 | 说明 |
|---|---|
theme.json | 位于包根，必须是合法 JSON |
theme.json.name | 必填，非空 |
theme.json.title | 必填，非空 |
theme.json.version | 必填，非空 |
| 首页模板 | index/index.html，或 index/index.htm，或根级 index.html |
建议（warnings，不阻断）
list/index.html、detail/index.html、common/header.html
static/静态资源目录（无静态文件可忽略）
- 包内介绍文件（README / docs）
theme.json 示例：
{
"name": "mytheme",
"title": "我的主题",
"version": "1.0.0",
"author": "你的名字",
"description": "一句话介绍",
"screenshot": "screenshot.png"
}模板目录结构与模板分层详见 模板开发 · 入门，主题配置字段 详见 模板开发 · 主题配置。
四、源码 / 插件包（type = source）
必需（errors）
| 文件 / 字段 | 说明 |
|---|---|
info.ini | 位于包根，key = value 键值对形式 |
info.ini.name | 必填；必须匹配 ^[a-z][a-z0-9_\-]{1,29}$ |
info.ini.title | 必填，非空 |
info.ini.version | 必填，非空 |
| 入口类文件 | {Studly(name)}.php，位于包根 |
name规则要特别注意：**小写字母开头，只能含小写字母、数字、下划线、连字符， 长度 2–30**。例如my_plugin、seo-boost合法，MyPlugin、2fa不合法。 入口类名由name转成大驼峰：my_plugin→MyPlugin.php。 若找不到规范入口类，会回退使用包根第一个.php并给出建议（不阻断）； 若包根一个.php都没有，则报错。
建议（warnings，不阻断）
config.php（后台配置项定义）
- 包内介绍文件（README / docs）
info.ini 示例：
name = my_plugin
title = 我的插件
intro = 一句话介绍这个插件能做什么
author = 你的名字
version = 1.0.0
require = 1.0.0插件目录结构与生命周期详见 插件开发 · 目录结构 与 插件开发 · 生命周期与钩子。
五、打包步骤
以插件为例（模板同理，换成模板目录）：
cd addons/my_plugin
zip -r ../../../my_plugin-1.0.0.zip . \
-x "*.git*" "*.DS_Store" "*__MACOSX*" "*.idea*"要点：
- zip 产物放在被压目录外面，否则会把自己再打进去，形成递归。
- 不要包含
.git、pycache、编辑器临时文件、.DS_Store。
- Windows 下用「发送到 → 压缩(zipped)文件夹」时，选中目录内的内容
再压缩，或直接压缩整个目录（公共顶层目录会被自动剥离）。
- 打包后建议本地先解压检查一次，确认
theme.json/info.ini位于包根。
六、常见驳回原因速查
| 现象 | 原因 | 处理 |
|---|---|---|
| 提示「缺少模板描述文件 theme.json」 | 描述文件不在包根，或被打进子目录且未形成公共前缀 | 把 theme.json 放到包根 |
| 提示「theme.json 不是合法的 JSON」 | 有尾随逗号 / 注释 / BOM | 用 JSON 校验器修正 |
| 提示「缺少首页模板」 | 没有 index/index.html | 补首页模板 |
| 提示「info.ini 的 name 需以小写字母开头…」 | 用了大写或含非法字符 | 改成 my_plugin 这类 |
| 提示「缺少插件入口类文件 Xxx.php」 | 类名与 name 不匹配 | 让文件名 = 大驼峰(name) |
| 提示包内存在非法路径 | 压缩时带了绝对路径 | 在包根目录下重新打包 |
| 提示介绍文件缺失（建议） | 没有 README / docs | 补一份 README.md |
| 提示可疑函数调用（建议） | 出现 eval/exec 等 | 确认安全或改用安全写法 |