源制作指南
约 2528 字大约 8 分钟
注
该文档仅适用于 >=2.6.0 版本
小猫影视支持两种视频源类型,让你可以轻松接入各种影视资源:
- maccms: 苹果 CMS 源(兼容 XML/JSON 格式)
- JS: JavaScript 扩展源(自定义实现)
配置格式
下面是一个完整的源配置示例:
// 简单数组
[
{/* Iconfig */
"id": "$UUID", // 唯一标识(不能重复)
"name": "d1y@的影视站", // 名称
"type": 0, // 源类型(0: maccms, 1: JS/universal)
"logo": "", // 图标 URL
"desc": "", // 源介绍
"nsfw": false, // 是否为 NSFW 内容
"status": true, // 源状态(true: 启用, false: 禁用)
"api": "", // API 地址
"extra": { // 额外配置
// ========== 通用配置 ==========
"jiexiUrl": "", // 视频解析接口 URL (可选,功能待完善)
"gfw": false, // 是否需要代理访问 (可选)
"searchLimit": 20, // 搜索结果每页数量 (可选,maccms默认20,JS默认10)
// ========== maccms 源配置特有分类 (type=0) ==========
"category": "", // 分类 ID 或名称 (可选,用于筛选特定分类)
// ========== JS 源配置 (type=1) ==========
"js": {
"category": "$JS函数名 | 真实的分类数组", // 分类函数或数组
"home": "$JS函数名", // 首页函数
"search": "$JS函数名", // 搜索函数
"detail": "$JS函数名", // 详情函数
"parseIframe": "$JS函数名" // 解析iframe函数(可选)
},
// ========== 模板配置 (可选) ==========
"template": "template_id", // 使用预定义的模板 ID(目前只有t4)
// ========== 视频嗅探配置 (可选) ==========
// 当 parseIframe 未实现时自动启用
"sniffer": {
"mode": 0, // 嗅探模式: 0=返回第一个URL, 1=返回所有URL
"timeout": 10000, // 超时时间(毫秒)
"customRegex": "", // 自定义正则表达式(可选)
"exclude": "", // 排除规则(可选)
"script": "", // 页面加载后执行的JS脚本(可选)
"initScript": "" // 页面初始化时执行的JS脚本(可选)
}
}
}
]
// 复杂对象
{
"sites": [], /* Array<Iconfig> */
"data": [], /* Array<Iconfig> */
"lives": [], /* Array<ILiveItem> */
}配置参数速查表
基础字段(所有源通用)
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
id | string | ✅ | - | 唯一标识,不能重复 |
name | string | ✅ | - | 源名称 |
type | int | ✅ | 0 | 源类型:0=maccms, 1=JS |
api | string | ✅ | - | API 地址 |
logo | string | ❌ | "" | 图标 URL |
desc | string | ❌ | "" | 源介绍 |
nsfw | bool | ❌ | false | 是否为 NSFW 内容 |
status | bool | ❌ | true | 是否启用 |
extra 字段(可选配置)
| 参数 | 类型 | 适用源 | 默认值 | 说明 |
|---|---|---|---|---|
jiexiUrl | string | 全部 | "" | 视频解析接口 URL |
gfw | bool | 全部 | false | 是否需要代理访问 |
searchLimit | int | 全部 | 20/10 | 搜索结果每页数量 |
category | string | maccms | - | 筛选特定分类 |
template | string | JS | - | 使用预定义模板 |
js | object | JS | - | JS 函数配置 |
sniffer | object | 全部 | - | 视频嗅探配置 |
TV 直播源配置包含以下字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | ✅ | 频道名称(如:CCTV1、湖南卫视) |
url | string | ✅ | 直播流地址(支持 m3u、txt 等格式) |
type | int | ✅ | 类型标识:0=m3u 格式,1=txt 格式 |
如何使用配置文件
将配置文件上传到可访问的静态资源网站(如 GitHub Pages、Vercel 等),然后在小猫影视中打开「视频源管理」,添加配置文件的 URL 地址即可。

使用订阅协议
小猫影视支持订阅协议 xm://sub?url=<配置文件URL>,用户点击链接即可自动添加源。例如:
xm://sub?url=https://example.com/source.jsonURL 加密规则(可选)
为了保护源地址或简化配置,小猫影视支持对 URL 进行 Base64 加密。
加密格式
所有加密的 URL 必须以 b 开头,后跟 Base64 编码的内容:
b<base64_encoded_content>支持的加密类型
1. 普通 URL 加密
直接对完整的 URL 进行 Base64 编码:
// 原始 URL
https://example.com/api/data.json
// 加密后(b + base64)
baHR0cHM6Ly9leGFtcGxlLmNvbS9hcGkvZGF0YS5qc29u2. GitHub 规则加密
对于托管在 GitHub 的配置文件,可以使用简化的 GitHub 规则:
格式: g<user>/<repo>#<branch>/<path>
g: GitHub 规则标识符<user>: GitHub 用户名<repo>: 仓库名#<branch>: 分支名(可选,默认为main)<path>: 文件路径(支持多级目录)
示例:
// GitHub 规则(指定分支)
gd1y/kitty#gh-pages/output/result.json
// 转换为
https://raw.githubusercontent.com/d1y/kitty/gh-pages/output/result.json
// 加密后
bZ2QxeS9raXR0eSNnaC1wYWdlcy9vdXRwdXQvcmVzdWx0Lmpzb24=// GitHub 规则(默认分支)
gd1y/kitty/data/source.json
// 转换为
https://raw.githubusercontent.com/d1y/kitty/main/data/source.json
// 加密后
bZ2QxeS9raXR0eS9kYXRhL3NvdXJjZS5qc29u苹果源(maccms)
小猫影视完整支持苹果 CMS 的资源接口,兼容 XML 和 JSON 两种格式。
如何找到苹果源
搜索「资源采集站」关键词,可以找到很多资源站列表
- 参考:https://14ysdg.com/archives/82
找到类似这样的 API 地址:
http://help.apibdzy.com
访问 API 地址,检查返回的数据格式
- 确认返回的是
xml或json格式 - 能看到影视数据结构就说明可用

- 确认返回的是
创建苹果源配置
找到可用的 API 后,按照下面的格式创建配置文件:
基础配置
[
{
"id": "$UUID",
"name": "百度资源",
"type": 0,
"logo": "",
"nsfw": false,
"api": "https://cj.apibdzy.com/inc/api.php"
}
]高级配置
如果需要更多控制,可以使用 extra 字段:
[
{
"id": "$UUID",
"name": "百度资源",
"type": 0,
"logo": "",
"nsfw": false,
"api": "https://cj.apibdzy.com/inc/api.php",
"extra": {
"category": "[]", // 使用静态分类
"gfw": false, // 是否需要代理访问
"sniffer": {} // 视频嗅探配置
}
}
]JS 扩展源
JS 扩展源让你可以自定义数据源的实现逻辑,适合接入各种非标准的影视网站。
开发工具
小猫影视提供了完整的开发工具链(位于 JS/ 目录):
- cli: 命令行工具,用于将你的实现导出为配置文件
- types: TypeScript 类型定义,提供完整的接口规范
JS 运行环境与 Polyfill
小猫影视的 JS 源运行在 Flutter JS 引擎中,为了让你的代码能够正常运行,我们提供了完整的 polyfill 支持:
已内置的 Polyfill
基础 API(js_polyfill.dart):
FormData: 表单数据处理URLSearchParams: URL 参数解析URL: URL 对象(部分支持)dayjs: 日期时间处理库
编码函数(polyfill.js):
btoa/atob: Base64 编码/解码encodeURI/decodeURI: URI 编码/解码encodeURIComponent/decodeURIComponent: URI 组件编码/解码escape/unescape: 字符串转义(已废弃但仍可用)TextEncoder/TextDecoder: 文本编码器
DOM API(dom_polyfill.js)⚠️ 仅为模拟环境:
window/document: 基础 DOM 对象(模拟)Element/Node: DOM 元素和节点(模拟)Event/EventTarget: 事件系统(模拟)XMLHttpRequest: HTTP 请求(模拟,不会真实发送请求)localStorage/sessionStorage: 本地存储(内存模拟)navigator/location/history: 浏览器对象(模拟)
使用示例
export default class MySource implements Handle {
async getHome() {
// 使用 Base64 编码
const encoded = btoa('小猫影视');
const decoded = atob(encoded);
// 使用 URL 编码
const url = encodeURIComponent('https://example.com/搜索');
// 使用 dayjs 处理日期
const now = dayjs().format('YYYY-MM-DD');
// 使用 URLSearchParams
const params = new URLSearchParams('page=1&limit=20');
const page = params.get('page');
return [];
}
}注意事项
⚠️ 环境限制:
- JS 引擎不是完整的浏览器环境,某些浏览器特有的 API 可能不可用
- DOM polyfill 是纯内存模拟,不会产生真实的 DOM 渲染或副作用
- DOM API 主要用于让依赖 DOM 的第三方库能够加载,不要依赖 DOM 操作来实现业务逻辑
💡 最佳实践:
- 优先使用标准 JavaScript API(如
JSON.parse、Array.map等) - 需要网络请求时,使用小猫影视提供的 HTTP 工具
快速开始
1. 创建项目
npm init -y2. 安装依赖
+ "@types/kitty": "https://gitpkg.vercel.app/waifu-project/movie/JS/types?dev",
+ "kitty": "https://gitpkg.vercel.app/waifu-project/movie/JS/cli?dev",3. 实现源逻辑
创建 demo.ts 文件,实现 Handle 接口:
export default class Demo implements Handle {
getConfig() {
return <Iconfig>{
id: 'demo',
name: 'JS引擎配置',
api: "https://d1y.movie",
nsfw: false,
type: 1
}
}
async getCategory() {
// TODO: impl this
return [
{ text: '电影', id: "1" },
{ text: '电视剧', id: "2" },
{ text: '综艺', id: "3" },
{ text: '动漫', id: "4" },
]
}
async getHome() {
// TODO: impl this
return <IMovie[]>[]
}
async getDetail() {
// TODO: impl this
return <IMovie>{ id, cover, title, remark, desc, playlist }
}
async getSearch() {
// TODO: impl this
return <IMovie[]>[]
}
async parseIframe() {
// TODO: impl this
return ""
}
}4. 生成配置文件
使用命令行工具导出配置:
# 查看帮助
bunx kitty-parse --help
# 生成配置文件
bunx kitty-parse -o result.json命令选项说明:
-o, --output <file>: 指定输出文件(默认:result.json)-d, --directory <dir>: 指定扫描目录-v, --verbose: 显示详细输出-h, --help: 显示帮助信息
JS 源高级配置
完整配置示例
{
"id": "advanced-source",
"name": "高级 JS 源",
"type": 1,
"api": "https://example.com",
"status": true,
"extra": {
// "template": "t4",
"js": {
"category": "getCategory",
"home": "getHome",
"search": "getSearch",
"detail": "getDetail",
"parseIframe": "parseIframe"
},
"searchLimit": 15,
"gfw": true, // 需要代理访问
"sniffer": {
"timeout": 20000,
"customRegex": "https?://cdn\\.example\\.com/.*\\.(m3u8|mp4)"
}
}
}参考资源
- 完整类型定义: index.d.ts
- 示例项目: https://github.com/d1y/kitty
视频嗅探功能
感谢道长 (@hjdhnx) 的原创实现:https://github.com/hjdhnx/pup-sniffer
什么是视频嗅探
视频嗅探是一个智能功能,可以自动从网页中提取真实的视频播放地址。当你遇到无法直接播放的视频链接时,嗅探功能会帮你找到可播放的视频资源。
自动触发条件
当满足以下条件时,小猫影视会自动启动视频嗅探:
- 在
getDetail()或getHome()中,视频链接被标记为iframe类型- 例如:
{ text: '第一集', id: '$iframe_url' }
- 例如:
- 源配置中没有实现
parseIframe方法
嗅探配置参数
你可以在源配置的 extra.sniffer 中自定义嗅探行为:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | int | 0 | 嗅探模式:0=返回第一个匹配的URL,1=返回所有匹配的URL |
timeout | int | 10000 | 超时时间(毫秒) |
customRegex | string | - | 自定义正则表达式,用于匹配特定格式的媒体 URL |
exclude | string | - | 排除规则,匹配的 URL 将被忽略(支持正则) |
script | string | - | 页面加载完成后执行的 JavaScript 脚本 |
initScript | string | - | 页面初始化时执行的 JavaScript 脚本 |
配置示例:
{
"extra": {
"sniffer": {
"mode": 0,
"timeout": 15000,
"customRegex": "https?://cdn\\.example\\.com/.*\\.(m3u8|mp4)",
"exclude": "ads\\.example\\.com|tracker\\.example\\.com",
"script": "document.querySelector('video')?.play();"
}
}
}常见问题
Q: 为什么嗅探不到视频?
可能的原因:
- 网页使用了加密或混淆技术
- 视频需要登录或付费才能观看
- 网站使用了特殊的播放器技术
- 网络连接不稳定或被限制
Q: 嗅探到的视频无法播放?
可能的原因:
- 视频链接有时效性限制,已过期
- 视频有防盗链保护(需要特定 Referer)
- 视频格式不被当前播放器支持
- 缺少必要的请求头(User-Agent 等)