短剧小程序源码拆包：竖屏剧场搭建、播放权限与自检

简介：面向希望切入短剧市场的前后端开发者与独立搭建者，这套小剧场短剧影视小程序源码提供从内容播放、用户管理到支付接入的一站式实现思路，适合在碎片化观看场景下快速验证付费短剧、会员订阅等业务模式，新手可借教程入门，有经验者可用于二次开发与功能扩展。压缩包共2000个文件、约77.25MB，以JavaScript、HTML、Markdown、CSS、JSON为主，辅以SQL备份和部署说明，覆盖前端页面、样式交互、项目说明、依赖配置与数据结构等层面；目录按应用代码、公共资源、扩展插件、框架核心与运行时数据分层组织，便于按模块查阅和维护。源码基于ThinkPHP的MVC结构，已对接易支付并修复已知问题，配套简易搭建教程可帮助理解前后端交互、数据库设计与支付闭环。目前已有448人学习下载，适合想缩短开发周期、降低试错成本的短剧小程序开发者参考。

1. 短剧小程序源码拆包：一套能跑起来的竖屏剧场该长什么样

拿到「新版小剧场短剧影视小程序源码」这类资源，多数人第一反应是翻目录找 app.json，结果发现前后端混在一起、文档只有一页截图。我这次是按「能不能在本地半小时起一个能播片的竖屏剧场」来验收的：短剧小程序和短剧 App 的核心链路其实就四段——剧集列表、分集播放、观看权限（免费集/解锁集）、播放记录续看。这套源码把四段都覆盖了，前端是原生小程序结构，后端带接口与数据表，附的搭建教程偏简版但关键配置项没漏。适合想做一个垂直短剧内容载体的小团队或个人开发者，不适合想直接拿去做大型内容分发的团队，原因后面讲到数据表和并发时会说清。

2. 环境与目录：先把工程骨架摸清楚再动手

短剧类项目最怕的不是跑不起来，是跑起来之后不知道哪个文件在管播放地址、哪个在管解锁逻辑。所以第一步不是急着装依赖，而是把目录结构读一遍，把「配置层 / 接口层 / 页面层 / 静态资源层」四块对上号。这一步花二十分钟，后面排错能省两小时，血泪经验。

2.1 目录分层与本次拆包的实际情况

按常见的小程序 + 服务端双端结构，这套源码大致是这样几块：

我一般会先确认三件事：request.js里的 baseURL 是不是写死的内网地址、server/config里数据库账号是不是占位符、server/sql下有没有完整的建表语句。这三项只要有一个是空的，后面必然翻车，而且报错信息往往是「网络异常」这种黑匣子式提示，排查成本极高。

2.2 本地起服务的具体命令

服务端大多是 Node 体系，先看package.json的 scripts 再决定命令，不要凭习惯敲：

# 进入服务端目录，先读脚本定义，别直接 npm start cd server cat package.json | grep -A 10 '"scripts"' # 安装依赖，国内网络环境建议先配镜像源 npm install --registry=https://registry.npmmirror.com # 执行建表脚本（以 MySQL 为例，库名和账号按 config 里的实际值替换） mysql -u root -p duanju_db < sql/init.sql # 启动服务，观察监听端口是否与前端 baseURL 一致 npm run start

npm install之后如果出现原生模块编译失败，先看 Node 版本，这类项目多数在 Node 16/18 上验证过；mysql那条命令里的库名和账号必须和server/config里的保持一致，否则建表建到了另一个库，接口查询会全部返回空数组，表现成「首页一直转圈」。启动后建议直接用 curl 打一个列表接口，确认服务端自身是通的，再去看小程序端：

# 验证剧集列表接口是否正常返回，路径以 server/routes 里的实际定义为准 curl -s "http://127.0.0.1:3000/api/drama/list?page=1&size=10" | head -c 500

返回结构里能看到code、data、list这类字段就说明链路通了。这一步千万别跳过，前端白屏的时候你至少能确定问题在前端还是在服务端。

2.3 前端 baseURL 与域名校验的两处必改

小程序前端要改的位置通常只有一个，就是请求封装文件里的域名常量：

// miniprogram/utils/request.js // 本地联调阶段用局域网 IP，真机预览必须换成电脑的 192.168.x.x，不能用 localhost const BASE_URL = 'http://192.168.1.100:3000/api'; const request = (url, method = 'GET', data = {}) => { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + url, method, data, header: { 'content-type': 'application/json' }, success: (res) => { // 后端约定 code=0 为成功，此处按实际返回结构调整 if (res.data && res.data.code === 0) { resolve(res.data.data); } else { reject(res.data || { message: '接口返回异常' }); } }, fail: (err) => reject(err) }); }); }; module.exports = { request, BASE_URL };

这段封装的价值在于把「成功判定」收在一处。很多开箱即用的源码里每个页面各写一遍if (res.data.code === 0)，一旦后端调整约定就要全局搜索改写，非常痛苦。你在自己项目里改造成本最低的做法，就是第一天就把它统一掉。

另外两个必改点：开发者工具里要勾选「不校验合法域名」用于本地 HTTP 联调；正式上线前必须在后台配置 request 和 downloadFile 两类合法域名，视频播放走的是 downloadFile 权限，只配 request 会出现「列表能刷出来、点播放没反应」的玄学现象。

3. 剧集与播放链路：列表、详情、播放三段的参数设计

短剧场景和普通点播的区别在于节奏极快——用户从刷到封面到点开播放通常不超过三秒，所以列表接口的字段冗余度、封面图尺寸、分集切片的粒度，直接决定了完播率。这套源码在列表里返回了分集数量和首集免费标记，是个合理设计，但播放地址的处理方式需要你自己收敛。

3.1 列表与详情接口的字段取舍

列表接口不该返回播放地址，只返回封面、标题、集数、简介、是否完结。详情接口再按剧集 ID 返回分集数组，每一集带上序号、时长、是否免费、播放地址（或播放地址的鉴权参数）。这样拆分的好处是列表页响应体积小，短剧 App 的列表页往往一屏六到八个封面，图大了就卡。

// 播放页：按剧集 ID 拉分集列表，并把「上次看到第几集」取出来用于续看 const { request } = require('../../utils/request'); Page({ data: { dramaId: '', episodes: [], current: 1 }, onLoad(options) { this.setData({ dramaId: options.id }); this.loadEpisodes(options.id); }, async loadEpisodes(dramaId) { const detail = await request(`/drama/detail?id=${dramaId}`); // 分集按 ep_no 升序，后端没排序的话这里补一刀 const episodes = (detail.episodes || []).sort((a, b) => a.ep_no - b.ep_no); const history = wx.getStorageSync(`history_${dramaId}`); this.setData({ episodes, current: history && history.ep <= episodes.length ? history.ep : 1 }); }, onEpisodeTap(e) { const ep = e.currentTarget.dataset.ep; const target = this.data.episodes.find((item) => item.ep_no === ep); if (!target.is_free) { // 付费集的拦截逻辑放在前端只是体验层，真实校验必须在服务端 return this.showUnlockDialog(target); } wx.setStorageSync(`history_${this.data.dramaId}`, { ep, ts: Date.now() }); this.playEpisode(target); } });

current的取值逻辑值得说一句：存储里记录的集数可能超过当前分集总数（剧集被下架、分集被删），所以必须做一次边界判断，否则会出现默认集数为 15、实际只有 10 集、播放器直接黑屏的情况。onEpisodeTap里的is_free判断只是体验层，真实校验一定在服务端，这一点在第 5 章会展开。

3.2 播放器组件的参数与竖屏适配

短剧是竖屏形态，播放器必须铺满宽度、按 9:16 或 3:4 自适应，并且默认自动播放、默认隐藏控制条、上下滑动切集。原生 video 组件能覆盖大部分需求，关键参数这么配：

// play.wxml 片段对应的配置对象，写在页面 data 里便于动态调整 playerConfig: { autoplay: true, // 短剧场景默认自动播，减少一次点击 loop: false, // 单集循环会让用户误以为卡住 muted: false, // 首次进入不要静音，短剧用户对声音有预期 showCenterPlayBtn: false, // 自动播时中间按钮会遮住画面 objectFit: 'cover', // 竖屏铺满，留黑边会显得内容单薄 enableProgressGesture: false // 禁掉横滑进度，避免与切集手势冲突 }

objectFit选cover意味着会裁掉一部分画面边缘，如果你的源片是 16:9 横屏转过来的，裁切会切掉字幕，这种情况改成contain并给容器加背景色更稳妥。手势冲突是竖屏剧场最常见的翻车点：横滑调进度和上下滑切集很容易互相打架，我的做法是进度控制只保留点按屏幕唤出的进度条，滑动手势全部让给切集。

3.3 视频地址的两种存法与管理方式

源码里对播放地址的处理有两种常见形态：一种是把完整 URL 存在数据库字段里，另一种是存对象存储的 key，播放时由服务端签名生成临时地址。前者简单但资源一迁就全线失效，后者多一步接口调用但可控。短视频剧集数量多、更新频繁，我建议走第二种，数据库只存video_key，播放接口返回带时效的地址：

// server/service/video.js 伪代码，演示签名地址的生成位置 async function getPlayUrl(episode) { // 免费集与已解锁集都走同一套签名逻辑，权限判断在调用前完成 const key = episode.video_key; if (!key) throw new Error('分集缺少视频文件'); // 有效期不宜过长，避免地址被外部长期复用 return storage.signUrl(key, { expires: 1800 }); }

expires设 1800 秒是个折中值：太短会导致用户看到一半地址过期、播放中断；太长则地址被复制出去后长期可用。如果你不打算接对象存储，退一步至少要把域名抽成配置项，别在数据库里写死带 IP 的地址，迁移时你会想把数据库删了重来。

4. 观看权限与数据表：解锁逻辑必须落在服务端

短剧项目的商业逻辑全在「哪几集免费、后面的怎么解锁」上，这也是最容易写成豆腐渣的地方。我见过不少源码把解锁状态存在前端 storage 里，清一下缓存就全解锁了，这种只能当 Demo 看。这套源码带了用户表、剧集表、分集表、观看记录表和订单/解锁记录表，骨架是够的，但要你自己把校验串起来。

4.1 五张核心表的关系与必要索引

索引这块别省。episode表如果没有(drama_id, ep_no)联合索引，详情页在分集数上百之后会明显变慢；watch_log表如果没有(user_id, drama_id)索引，续看查询在用户量大之后就是全表扫描。这两条是做短剧类应用最基础的性能保险。

4.2 解锁校验的执行顺序

一次播放请求进来，服务端应该按固定顺序判断，任何一步失败都直接拒绝，不要图省事合并条件：

// server/service/permission.js async function checkPlayable(userId, dramaId, epNo) { // 1. 剧集是否上架 const drama = await db.drama.findByPk(dramaId); if (!drama || drama.status !== 1) return { ok: false, msg: '剧集已下架' }; // 2. 分集是否存在 const ep = await db.episode.findOne({ where: { drama_id: dramaId, ep_no: epNo } }); if (!ep) return { ok: false, msg: '分集不存在' }; // 3. 免费集直接放行，这是唯一可以跳过用户判断的分支 if (ep.is_free === 1) return { ok: true, ep }; // 4. 付费集必须登录 if (!userId) return { ok: false, msg: '请先登录' }; // 5. 查解锁记录，注意按 user + drama + ep 三元组精确匹配 const unlocked = await db.unlock_log.findOne({ where: { user_id: userId, drama_id: dramaId, ep_no: epNo } }); if (!unlocked) return { ok: false, msg: '该集未解锁' }; return { ok: true, ep }; }

顺序不能乱。先判上架再判分集，是为了避免下架剧集仍能通过直链播放；付费集先判登录再查解锁记录，是为了给前端返回明确提示（未登录 vs 未解锁），用户体验差别很大。还有一点，unlock_log的查询一定要三元组精确匹配，只按user_id + drama_id查会让用户解锁一集就等于解锁全剧，这种 bug 上线后基本等于送钱。

4.3 观看进度与续看的写入时机

进度写入不要太频繁，短剧一集常常一两分钟，用户随时退出。我的做法是播放进度达到 30% 时写一次、播放结束时写一次，暂停不写：

// 播放页进度上报，节流由页面层控制 async function reportProgress(dramaId, epNo, percent) { if (percent < 30 && percent < 99) return; // 未达阈值不写，降低写入压力 await request('/watch/report', 'POST', { drama_id: dramaId, ep_no: epNo, percent: Math.floor(percent), updated_at: Date.now() }); }

服务端对watch_log用INSERT ... ON DUPLICATE KEY UPDATE做覆盖写，避免每次上报都新增一行。若你的表没设唯一键，写入会无限膨胀，一个月后这张表变成最大的表，查续看慢到用户以为没这功能。

5. 避坑清单：这套源码落地时最容易翻车的五处

以下五条都是这类短剧小程序源码在真实落地中最常见的故障，按「现象 → 原因 → 解决」排列，遇到问题时对照着查，比盲翻日志快。

播放地址能拿到但视频一直转圈。现象是接口返回 200、拿到了 URL，播放器黑屏转圈。原因九成是合法域名没配 downloadFile 权限，或者返回的地址是内网 IP 而真机不在同一网段。解决方式是先在小程序后台把 downloadFile 合法域名补齐，再确认返回地址在手机浏览器里能直接打开；本地联调阶段临时勾选「不校验合法域名」，但不要带进正式环境。

首页列表一直加载不出数据。现象是页面骨架屏一直转。原因通常是 baseURL 还写着 localhost，或者服务端监听的端口与前端配置不一致，也有一种是建表建到了另一个库导致查询返回空数组但接口仍返回成功。解决方式是先用 curl 在电脑上打接口，返回正常再查前端配置，两边分别定位，不要假设是前端问题。

部分集数点了没反应。现象是第 1 集正常、第 8 集点击无响应。原因是分集数据里video_key或播放地址为空，而前端没做空值兜底直接抛错。解决方式是详情接口返回前做一次数据完整性校验，缺文件的集数标记为不可播放并在前端置灰，同时后台给运营一个缺资源清单，别让用户替你发现问题。

修改代码后小程序端不生效。现象是接口逻辑改了、前端还是老样子。原因是开发者工具缓存了编译产物，或者你改的是miniprogram目录却被上传了另一份打包产物。解决方式是清缓存重新编译，并在提交前核对仓库里是否同时存在两份同名工程目录，这种重复目录在二手源码包里非常常见。

续看总从第一集开始。现象是明明看了第七集，下次进来还是第一集。原因是进度写入用了updated_at但查询按created_at倒序，或者 storage 的 key 拼错（history_前缀和后缀写反）。解决方式是统一存储键的拼装函数，写入与读取都走同一函数，同时在服务端按(user_id, drama_id)唯一键做覆盖写，避免多行记录导致取到旧的。

提示：以上五条里有三条的根因都是「配置项分散在多处」。接手这类源码的第一步，我建议把 baseURL、端口、数据库、存储域名四项全部抽到一个配置文件，并在启动时打印一次生效值，后面所有诡异问题都先看这四行。

6. 上线前的自检打法：把验收做成可复跑的脚本

做到能播只是及格线，真正决定这套源码能不能用的，是上线前你怎么验收。我现在的习惯是不靠手点，把关键链路写成一组可重复执行的接口检查，每次改完代码跑一遍，比人工点十遍靠谱得多。这套短剧小程序的验收至少覆盖四条链路：列表能出、详情分集完整、免费集能播、付费集未解锁时被拦。

#!/bin/bash # check.sh 上线前自检，BASE 按环境替换 BASE="http://127.0.0.1:3000/api" # 1. 列表接口必须有数据 LIST=$(curl -s "$BASE/drama/list?page=1&size=5") echo "$LIST" | grep -q '"list"' || { echo "列表接口异常"; exit 1; } # 2. 取第一部剧的详情，分集数必须大于 0 DRAMA_ID=$(echo "$LIST" | sed -n 's/.*"id":\([0-9]*\).*/\1/p' | head -1) DETAIL=$(curl -s "$BASE/drama/detail?id=$DRAMA_ID") echo "$DETAIL" | grep -q '"episodes"' || { echo "详情接口异常"; exit 1; } # 3. 免费集应放行，付费集在未登录时应被拒绝 FREE=$(curl -s "$BASE/play/url?drama_id=$DRAMA_ID&ep=1") echo "$FREE" | grep -q '"url"' || { echo "免费集播放地址缺失"; exit 1; } LOCKED=$(curl -s "$BASE/play/url?drama_id=$DRAMA_ID&ep=99") echo "$LOCKED" | grep -q '"url"' && { echo "付费集未做拦截，存在越权风险"; exit 1; } echo "自检通过"

这个脚本的写法值得解释几处：grep -q只关心是否存在不输出内容，适合放在流程里做断言；第三步故意请求一个不存在的第 99 集，是为了验证服务端在分集不存在时返回的是错误而不是地址，这个用例比正常用例更能暴露权限漏洞。参数size、集数编号都要按你项目的实际接口调整，别照抄。

再补一层数据侧的验收，很多人只测接口不测数据，最后上线才发现分集顺序乱、总集数对不上：

这张表我一般会让它跑成一条 SQL 加一个小脚本，每次内容更新后执行一次，尤其是批量导入剧集之后——批量导入最容易出缺号和对不上的问题，人工抽查根本查不全。

还有一个容易被忽略的点：total_ep字段到底是「已上线集数」还是「计划集数」。短剧经常边更边播，如果total_ep写的是计划数，前端按它渲染分集格子就会出现一片空白格，用户以为内容缺失。我的做法是字段语义统一为已上线集数，计划集数另开一个字段只给运营后台用，前端永远只认已上线数。这类字段语义不一致的问题，是二手源码包里最难靠读代码发现、只能靠数据比对暴露出来的。

从那以后我每次拿到这类小程序源码，都强制先跑一遍「列表—详情—免费集—付费集」四条断言的脚本，通过了才允许自己开始改业务代码，不然改到一半发现底座是漏的，返工的时间够重写一遍。这套流程希望帮到你。

本文还有配套的精品资源，点击获取