ckplayer-plus

基于 ckplayer X3 的工程化封装：支持 npm / ESM，并提供 Vue 2.7+/3 与 React 组件。

免责声明：本包为社区/工程化封装，非 ckplayer 官方包。播放内核来自 ckplayer（MIT）。完整能力与参数请同时参考 官方手册。npm 上的官方包名为 ckplayer，请勿混淆。

安装（只需这一步）

npm i ckplayer-plus

不必再单独安装 hls.js / flv.js / mpegts.js。
包内已附带对应脚本；播放时会按视频地址自动选择插件并按需加载。

自动识别规则（默认开启）

| 地址特征 | 行为 | |----------|------| | .mp4 等浏览器可直接播的格式 | 原生 <video>，不加载流媒体脚本 | | .m3u8 | 自动使用 hls.js（Safari 若原生支持则仍走原生） | | .flv | 自动使用 flv.js | | .ts / .m2ts / .mts | 自动使用 mpegts.js |

关闭自动识别：autoPlug: false，并自行传 plug。

引入样式（必做）

import 'ckplayer-plus/style.css'

最简用法（mp4 / m3u8 都这样写）

import ckplayer from 'ckplayer-plus'
import 'ckplayer-plus/style.css'

const player = new ckplayer({
  container: '#player',
  video: url // 可以是 mp4 或 m3u8，无需再写 plug
})

Vue：

<CkPlayer :video="url" height="400px" />

React：

<CkPlayer video={url} height="400px" />

配置说明（哪些要写、哪些不用写）

常用且推荐

| 配置 | 是否必须 | 默认 | 说明 | |------|----------|------|------| | container | 核心 API 必须；组件不用 | — | 播放器挂载节点。Vue/React 组件内部自动创建，不要传 | | video | 必须 | — | 视频地址或清晰度数组 | | poster | 可选 | '' | 封面图 | | autoplay | 可选 | false | 自动播放。课程/断点续播请保持 false：有 seek 时组件会强制关闭自动播，只定位进度，需用户点击播放 | | volume | 可选 | 0.8 | 音量 0–1 | | live | 可选 | false | 直播相关 | | width / height | 组件可选 | 100% / 400px | 仅 Vue/React 组件样式 |

一般不用写（已内置默认行为）

| 配置 | 默认 | 说明 | |------|------|------| | autoPlug | true | 按地址自动选插件；通常保持默认即可 | | plug | 自动 | 仅在要强制指定或 autoPlug: false 时填写：hls.js / flv.js / mpegts.js | | preferBuiltinPlug | true | 优先加载本包内置脚本，避免复用页面上其它全局 Hls | | cdnFallback | true | getPath 失败时回退 jsDelivr；内网无外网请设 false 并配 pluginPath（或确保能访问 /node_modules/ckplayer-plus/dist/） | | pluginPath | 自动 | 插件脚本根路径。默认：window.ckplayerBasePath → 可信 script/dist → jsDelivr CDN → /node_modules/ckplayer-plus/dist/。勿设成 /src/；也勿依赖当前页相对路径 | | seek | 0 | 续播秒数。HLS 对齐分片起点缓冲后再定位；只 seek 不自动 play，避免 Network 出现 canceled .ts | | loaded | — | 只支持函数；字符串形式已禁用（防 XSS） |

进阶（按需）

| 配置 | 说明 | |------|------| | timeScheduleAdjust | 5 时只能在已看进度内拖动；续播请同时传数字 seek | | crossOrigin | 跨域视频 / 截图等场景 | | cookie | 进度记忆；组件默认使用实例唯一名，避免多实例冲突 | | language | 语言包名，如 en、zh.hk（需能加载到 language/*.js） | | loop / controls 等 | 与官方 ckplayer 一致，见手册 | | window.ckplayerBasePath | 全局指定插件根目录（以 / 结尾），优先于 CDN | | window.ckplayerPlusCdn | 自定义 CDN 根地址（覆盖默认 jsDelivr） |

插件加载优先级

1. preferBuiltinPlug: false 且页面已有全局 Hls / flvjs / mpegts → 直接复用
2. 否则加载本包脚本：pluginPath 或可信的 window.ckplayerBasePath（仅 dist / npm 包路径会自动设置；/src、assets、.vite/deps、chunk 目录会忽略）
3. 传统 <script src=".../ckplayer.min.js"> 同级目录推导（不会再用页面最后一个无关 script，避免 Vite 指到 /src/main.js）
4. cdnFallback !== false 时回退：https://cdn.jsdelivr.net/npm/[email protected]/dist/；若本地路径 404 会再自动重试一次 CDN
5. 仍无可靠根时：站点根相对 /node_modules/ckplayer-plus/dist/（Vite 开发态常用；不是当前路由目录下的相对路径）

Vue 2.7 / Vue 3 / React（Vite/Webpack）：直接 import { CkPlayer } from 'ckplayer-plus/vue'（或 /react）即可。默认会走 jsDelivr CDN；内网请把 dist/hls.js 等拷到静态目录并设 pluginPath，同时 cdnFallback: false。
不要指望 hls.js/hls.min.js 这种相对路径——在 /student/course 一类 SPA 路由下会错误请求 /student/hls.js/...。
本地调试本仓库 demo：先 npm run build，再用静态服务打开 examples/demo.html（dist/ 被 gitignore，不重建会跑到旧逻辑）。
样式请使用 import 'ckplayer-plus/style.css'，保证 ./images/ 图标能被打包工具解析。

Vue 2.7 / Vue 3

支持 Vue 2.7+ 与 Vue 3（需从 vue 解析 h，与 peerDependencies 一致）。

<template>
  <CkPlayer :video="url" :seek="16" poster="/poster.png" height="400px" @play="onPlay" />
</template>

<script>
import { CkPlayer } from 'ckplayer-plus/vue'
import 'ckplayer-plus/style.css'

export default {
  components: { CkPlayer },
  data() {
    return { url: 'https://example.com/a.m3u8' } // 或 .mp4
  },
  methods: { onPlay() {} }
}
</script>

断点续播：seek 用 :seek 或 options.seek 在创建时传入；不要在 @ready 里再 player.seek(16)，否则会重复加载 HLS、取消 .ts 分片导致卡住。有 seek 时不会自动播放，定位完成后点中央播放按钮即可。切集/切换清晰度同样不强制自动播。

SSR（Nuxt 等）请用 <ClientOnly>，仅在浏览器初始化。

React

import { CkPlayer } from 'ckplayer-plus/react'
import 'ckplayer-plus/style.css'

<CkPlayer video={url} height="400px" onPlay={() => {}} />

Next.js 使用 Client Component 或 dynamic(..., { ssr: false })。

脚本标签

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.css" />
<script src="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.min.js"></script>
<div id="player" style="width:800px;height:450px;"></div>
<script>
  new ckplayer({
    container: '#player',
    video: 'https://example.com/video.mp4'
  })
</script>

重要说明

| 主题 | 说明 | |------|------| | SSR | 依赖 document，必须客户端初始化 | | 移动端自动播 | 常需 volume: 0 或用户手势 | | dash.js | 未实现 | | 体积 | 主包含流媒体 min 脚本以便「只装一个包」；运行时仍按需加载 |

开发与发布

npm install
npm run build
npm publish --access public

License

MIT。内置的 hls.js / flv.js / mpegts.js 遵循各自许可证（多为 Apache-2.0）。