ckplayer-plus

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。
包内已附带对应脚本；播放时会按视频地址自动选择插件并按需加载。

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

关闭自动识别：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" />

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

常用且推荐

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

进阶（按需）

插件加载优先级

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/ckplayer-plus@x.y.z/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>

重要说明

开发与发布

npm install
npm run build
npm publish --access public

License

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