xhs-minitool-creator

小红书「小工具」项目脚手架：创建、构建、打包、合规校验，一条命令完成。

你不需要先啃小红书小工具的平台规范，脚手架已把平台约束内置到构建配置与校验规则中。用它产出的 zip 直接上传创作服务平台即可。

快速开始

npx xhs-minitool-creator my-tool -y
cd my-tool
npm install
npm run build   # 产出 my-tool-xhs-minitool.zip，上传创作服务平台即可

交互式创建（自定义标题 / 描述）：

npx xhs-minitool-creator my-tool

命令

| 命令 | 作用 | | --- | --- | | npm run dev | 本地预览（Vite dev server） | | npm run build | 构建 + 打包，输出 <name>-xhs-minitool.zip | | npm run validate | 静态合规校验（输出 ERROR / WARNING 汇总） | | npm run skill | 查看项目内置官方规范版本 |

CLI 子命令 create / pack / validate / skill，详见 npx xhs-minitool-creator --help。

create 选项：--yes（跳过交互）、--title、--desc。

生成的项目

• Vite 项目，构建预设已内置平台约束，输出目录 xhs-minitool/
• 示例页面：单页多视图切换、适配平台原生导航栏与安全区
• 官方打包规范 minitool-zip-builder 快照（.agents/skills/），可直接供 AI 参考辅助开发

平台约束速览

• 完全离线：禁 fetch / XMLHttpRequest / WebSocket；外部 http(s):// 资源（图片、字体、CDN 脚本）必须下载进包改相对路径
• CSP 限制：禁内联 <script> 与行内事件（onclick= 等），脚本必须外置 + addEventListener
• 经典脚本：产物不允许 type="module" / import（离线环境下模块解析不可靠）——脚手架打包时自动转换，勿自行改回
• 单页应用：容器不打开新页面，多视图在单页内用 JS 切换 DOM
• WebView 基线低：Chrome 61 / ES2017。构建预设已设 build.target: ['es2017', 'chrome61']，若自己覆盖 Vite 配置别把它弄丢（否则 ?? 等 ES2020 语法会泄漏，真机白屏无报错）
• 体积：zip 硬上限 10 MiB，建议 ≤ 2 MiB；单条 Base64 ≤ 1 MiB
• 禁用 API：window.open、Worker、剪贴板、地理定位、设备传感器、WebAssembly 等（validate 会扫描）
• 安全区：viewport-fit=cover + env(safe-area-inset-*)，且顶部需为平台原生导航栏让位
• 原生能力：官方提供 4 个 JSBridge API（发笔记、存相册等，见 .agents/skills/ 内 jsbridge-api.md）

npm run validate 内置上述规则的静态扫描；静态检查无法覆盖运行时行为，交付前务必真机预览。

更新官方规范

官方规范经小红书 CDN 分发，无稳定 latest 端点（URL 含时间戳），需手动更新：

npx xhs-minitool-creator skill update --url <官方 .skill 包地址>

编程式使用

import { defineMinitoolConfig } from 'xhs-minitool-creator/vite';
import { pack, validateDir } from 'xhs-minitool-creator';

打包器说明

打包优先使用系统 zip 命令（macOS 自带），未安装则回退内置纯 Node 实现，两条路径产物一致；校验与 zip 读写零系统依赖（Windows / Linux 均可用）。

说明

• 本工具与小红书官方无隶属关系，内置规范内容版权归小红书
• 平台规则可能调整，关键决策以创作服务平台实时规则为准

License

MIT