Merge pull request #72 from langyuxiansheng/release/v2.0.0

Release/v2.0.0
2026-06-05 13:38:12 +08:00 · 2026-05-23 23:53:33 +08:00 · 2026-05-23 23:53:33 +08:00 · 83fa14457f
commit 83fa14457f
parent cdf70ab208 01ede92ed6
46 changed files with 6939 additions and 3827 deletions
--- a/.browserslistrc
+++ b/.browserslistrc
@ -1,2 +0,0 @@
-> 1%
-last 2 versions
--- a/.eslintrc.js
+++ b/.eslintrc.js
@ -1,23 +0,0 @@
-module.exports = {
-    root: true,
-    env: {
-        node: true,
-        browser: true,
-        es6: true
-    },
-        'extends': [
-        'plugin:vue/essential',
-        'eslint:recommended'
-    ],
-    rules: {
-        'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off',
-        'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off'
-    },
-    parserOptions: {
-        parser: 'babel-eslint'
-    },
-
-    globals: {
-        'Aliplayer': false
-    },
-}
--- a/.gitignore
+++ b/.gitignore
@ -1,6 +1,7 @@
 .DS_Store
 node_modules/
 *.map
+docs/
 # local env files
 .env.local
 .env.*.local
--- a/GITHUB_ISSUES_TODO.md
+++ b/GITHUB_ISSUES_TODO.md
@ -0,0 +1,268 @@
+# GitHub Issues Todo
+
+Fetched from `langyuxiansheng/vue-aliplayer-v2` open issues on 2026-05-23.
+
+Source: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues
+
+## Summary
+
+- Open issues recorded: 25
+- Main themes: Vue 3 compatibility, SDK loading/lifecycle, FLV/HLS/RTMP playback, Aliplayer SDK version drift, skin/custom UI configuration, documentation gaps.
+- Implementation pass on 2026-05-23: Vue 3 rewrite landed, SDK default updated to the new `imp-web-player` path, wrapper-level lifecycle/loading/playback helpers were added. Items marked "Code status" below are handled in this repository unless noted as upstream/documentation-only.
+
+## Compatibility And Packaging
+
+### #34 please support vue3.x
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/34
+- Created: 2020-12-08
+- Comments: 3
+- Problem: users request Vue 3 support.
+- Notes: comments mention a third-party Vue 3/Vite fork/package `vue-aliplayer-v3`; current project is Vue 2 based.
+- Follow-up: decide whether to add Vue 3 support in this package, publish a separate Vue 3 package, or document Vue 2-only support.
+- Code status: fixed in v2.0.0 rewrite. Vue 2 users must stay on 1.x.
+
+### #35 安装之后引用就直接报这个问题
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/35
+- Created: 2020-12-23
+- Comments: 3
+- Problem: Vue 3 usage throws `Cannot read property '_c' of undefined` from `vue-aliplayer-v2.umd.min.js`.
+- Notes: maintainer identified likely cause as Vue version mismatch; overlaps with #34.
+- Follow-up: treat as Vue 3 compatibility/package-entry issue.
+- Code status: fixed by replacing the Vue 2 UMD build with Vue 3/Vite library output.
+
+### #65 VueAliplayerV2在vue中使用报错
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/65
+- Created: 2022-06-12
+- Comments: 1
+- Problem: user reports usage error with screenshot only.
+- Notes: another user reported the same issue in 2023.
+- Follow-up: inspect screenshot manually when triaging; likely packaging/import/runtime compatibility.
+- Code status: likely fixed by Vue 3 package rewrite and typed exports; still needs reporter repro if screenshot covers another error.
+
+### #45 关于浏览器兼容的问题
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/45
+- Created: 2021-03-23
+- Comments: 1
+- Problem: works in Chrome 89, player component does not display in Chrome 59.
+- Notes: current wrapper relies on upstream Aliplayer SDK compatibility.
+- Follow-up: define supported browser matrix and test whether transpilation/polyfills or SDK version is the blocker.
+- Code status: documented as upstream SDK/browser support. v2 build targets modern Vue 3/Vite environments.
+
+### #46 请问，我使用uniapp安装aliplayerV2的问题
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/46
+- Created: 2021-03-25
+- Comments: 1
+- Problem: using npm install in uni-app, player buttons/components do not show.
+- Notes: maintainer had not tested uni-app.
+- Follow-up: decide whether uni-app is supported; if yes, add setup notes and a minimal repro.
+- Code status: not claimed as fixed. Needs a uni-app repro because this package targets Vue 3 web apps.
+
+### #70 建议升级阿里云播放器到最新版
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/70
+- Created: 2023-04-12
+- Comments: 0
+- Problem: default SDK is outdated; user changed CSS/JS defaults to Aliplayer `2.15.2`.
+- Notes: user also mentions missing source maps because Aliplayer is closed source.
+- Follow-up: verify latest stable Aliplayer SDK URL, update defaults if safe, and document how to override SDK URLs.
+- Code status: fixed. Default SDK now uses `apsara-media-box/imp-web-player/2.37.0`; `sdkVersion`, `cssLink`, and `scriptSrc` are configurable.
+
+## SDK Loading And Lifecycle
+
+### #71 优化建议
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/71
+- Created: 2024-08-02
+- Comments: 2
+- Problem: each created player reportedly adds another CSS and JS resource.
+- Notes: comment references newer `apsara-media-box/imp-web-player/2.16.3` resource URLs and a multi-player example.
+- Follow-up: reproduce with multiple create/destroy cycles and verify whether duplicate resource tags appear under current component logic.
+- Code status: fixed in shared SDK loader. It caches CSS/JS by URL and avoids duplicate tags for multiple players.
+
+### #62 多屏播放后，只销毁最后一个播放实例
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/62
+- Created: 2022-03-25
+- Comments: 2
+- Problem: in `v-for`, clearing the list only destroys the last player instance.
+- Notes: reporter says FLV did not reproduce, HLS did reproduce.
+- Follow-up: test multi-instance destroy with HLS and inspect player ID/ref/lifecycle handling.
+- Code status: improved. Component now guards async init after unmount and disposes each instance independently; still needs real HLS multi-player regression test.
+
+### #69 Uncaught TypeError: s._options is null
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/69
+- Created: 2023-03-29
+- Comments: 0
+- Problem: runtime error `s._options is null`, screenshot only.
+- Follow-up: inspect screenshot and try to reproduce around destroy/re-init or options mutation.
+- Code status: improved. Init is token-guarded and avoids creating stale players after fast option/source changes.
+
+## Playback Failures And Stream Behavior
+
+### #11 rtmp html5模式下不能播放
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/11
+- Created: 2020-06-10
+- Comments: 3
+- Problem: RTMP cannot play in HTML5 mode after Flash deprecation.
+- Notes: comment says RTMP only works with Flash; another suggests FLV.js.
+- Follow-up: document RTMP limitation clearly; avoid promising HTML5 RTMP support unless using another playback strategy.
+- Code status: documented limitation. RTMP H5 support is not fixed in wrapper.
+
+### #21 直播，不能播放flv格式的视频
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/21
+- Created: 2020-08-10
+- Comments: 1
+- Problem: FLV live stream fails both by `source` and dynamic `loadByUrl`.
+- Notes: maintainer suggested validating stream in VLC and checking Aliplayer config.
+- Follow-up: create verified FLV live test case and document required options.
+- Code status: improved. Wrapper infers `format: 'flv'`; `lowLatency` adds FLV live buffer defaults. Needs real FLV source validation.
+
+### #24 mp4格式视频加载错误4400
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/24
+- Created: 2020-09-27
+- Comments: 4
+- Problem: large or special MP4 URL reports error 4400; user says autoplay is false but play still appears to trigger.
+- Notes: maintainer suspected URL permissions/cross-origin/path encoding; reporter later said the URL contains Chinese characters.
+- Follow-up: test encoded vs unencoded URLs, autoplay false behavior, and error handling for cross-origin/private MP4.
+- Code status: improved. Wrapper now `encodeURI`s source URLs by default to handle Chinese filenames. Cross-origin/private URL failures remain source/server issues.
+
+### #37 发现m3u8视频播放时的问题
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/37
+- Created: 2021-01-07
+- Comments: 1
+- Problem: M3U8 quality switching is delayed; after switching and refreshing, playback fails.
+- Follow-up: reproduce with multi-quality M3U8 source and inspect whether wrapper re-init/load flow loses format or quality state.
+- Code status: improved. Wrapper infers source format and rebuilds player on cross-format changes instead of always calling `loadByUrl`.
+
+### #52 flv直播刷新页面视频卡住
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/52
+- Created: 2021-06-16
+- Comments: 3
+- Problem: FLV live video gets stuck after page refresh.
+- Notes: reporter confirmed issue was still unresolved in 2021.
+- Follow-up: include in FLV live repro matrix with #21 and #68.
+- Code status: improved by FLV format inference, async init guards, and `lowLatency`; still needs real stream repro.
+
+### #68 播放Flv视频直播时，时间长了后会延迟几分钟
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/68
+- Created: 2022-12-17
+- Comments: 0
+- Problem: FLV live stream accumulates several minutes of latency over time.
+- Follow-up: check Aliplayer FLV buffer options such as stash buffer settings and live latency handling.
+- Code status: improved. `lowLatency` applies `enableStashBufferForFlv: false` and `stashInitialSizeForFlv: 128` unless explicitly overridden.
+
+## Playback APIs And Source Modes
+
+### #43 vid+palyauth播放问题
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/43
+- Created: 2021-03-06
+- Comments: 5
+- Problem: `replayByVidAndPlayAuth` appears undefined from both `getPlayer()` and component ref.
+- Notes: later comment says methods like `replay()` and `pause()` were also undefined; maintainer notes multiple refs become arrays; user later resolved.
+- Follow-up: improve docs for `$refs` in single vs multiple-player usage and when methods are available.
+- Code status: fixed for Vue 3 docs. README now shows typed `ref<VueAliplayerV2Expose | null>`.
+
+### #49 这个不支持vid+playauth播放吗
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/49
+- Created: 2021-05-18
+- Comments: 3
+- Problem: question about `vid + playauth` playback support.
+- Notes: comment says it works when adding `encryptType: 1`; later user asks what else is required.
+- Follow-up: add working `vid + playauth` example and option notes.
+- Code status: documented. `vid + playauth` is supported through `options`; ref method remains exposed.
+
+## UI, Skin, And Extension Features
+
+### #53 播放按钮
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/53
+- Created: 2021-06-21
+- Comments: 14
+- Problem: users ask how to center play button, configure quality/subtitle options, change cover, and adjust progress/button colors.
+- Notes: maintainer answered that `skinLayout` must be placed inside `options`; example uses `skinLayout: [{ name: 'bigPlayButton', align: 'cc' }]`.
+- Follow-up: add skin customization examples to README.
+- Code status: partially documented through options passthrough. More visual skin examples can be added later.
+
+### #55 请问我要把清晰度切换单独放到设置外面要怎么弄呢？
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/55
+- Created: 2021-06-22
+- Comments: 1
+- Problem: user wants quality switch outside the settings menu.
+- Notes: maintainer pointed to Aliplayer skin settings docs.
+- Follow-up: document whether this is possible through `skinLayout` or requires custom components.
+- Code status: documented as Aliplayer skin/custom component responsibility.
+
+### #57 自定义组件
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/57
+- Created: 2021-07-06
+- Comments: 4
+- Problem: user asks whether Aliplayer custom component API is supported for a playlist.
+- Notes: maintainer says SDK should support it, but another user says adding `components` in `options` does not work unless custom component JS is separately loaded.
+- Follow-up: verify custom component loading order and provide an example if supported.
+- Code status: improved. Added `componentScripts` to load custom component scripts before player init; README includes example.
+
+### #61 播放失败页面自定义
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/61
+- Created: 2021-09-24
+- Comments: 1
+- Problem: clicking refresh on the player error page refreshes the whole page; user wants local refresh or custom refresh handler.
+- Notes: maintainer says the error page comes from Aliplayer.
+- Follow-up: check whether SDK exposes error UI customization or whether wrapper can expose a local retry pattern.
+- Code status: improved. Added `reload()` / `retry()` exposed methods for local retry; SDK error UI itself remains upstream.
+
+### #67 跑马灯功能可以用吗
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/67
+- Created: 2022-10-08
+- Comments: 0
+- Problem: user asks whether marquee/watermark scrolling text is available.
+- Follow-up: verify Aliplayer support and document unsupported/supported approach.
+- Code status: documented via `componentScripts` + `options.components`; availability depends on the loaded Aliplayer custom component.
+
+### #59 如何关闭track
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/59
+- Created: 2021-08-20
+- Comments: 1
+- Problem: player sends tracking POST requests to `https://videocloud.cn-hangzhou.log.aliyuncs.com/logstores/newplayer/track`; user wants to disable.
+- Notes: a comment suggests deleting `postWithHeader`, which is not a clean wrapper-level solution.
+- Follow-up: find official SDK option, if any; otherwise document limitation.
+- Code status: opt-in mitigation added. `disableTracking` can block known Aliplayer tracking URLs at wrapper level.
+
+## Format And Capability Questions
+
+### #60 能播vr视频或者vr直播吗
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/60
+- Created: 2021-09-16
+- Comments: 1
+- Problem: asks whether VR video or VR live can be played.
+- Notes: maintainer had not tested.
+- Follow-up: verify upstream Aliplayer capability and document scope.
+- Code status: documentation-only. Wrapper passes options through but does not implement VR rendering itself.
+
+### #66 支持AVI 格式的视频吗？
+
+- Link: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/66
+- Created: 2022-09-07
+- Comments: 0
+- Problem: asks whether AVI format is supported.
+- Follow-up: document supported formats according to upstream Aliplayer/browser support.
+- Code status: documented format scope. AVI is not claimed as supported by this wrapper.
--- a/README.en-US.md
+++ b/README.en-US.md
@ -0,0 +1,551 @@
+# vue-aliplayer-v2
+
+English | [简体中文](./README.md)
+
+A Vue 3 wrapper for the Aliyun Web Player Aliplayer SDK. v2 is rebuilt with Vue 3, TypeScript, and Vite. It supports URL playback, VID + PlayAuth, STS credentials, live streams, low-latency FLV, automatic format inference, License injection, extension component scripts, multiple player instances, and common player instance methods.
+
+> v2 no longer supports Vue 2. For Vue 2 projects, keep using `vue-aliplayer-v2@1.x`.
+
+## Demo
+
+- Project demo: https://langyuxiansheng.github.io/vue-aliplayer-v2/
+- Official Aliplayer demo: https://player.alicdn.com/aliplayer/index.html
+- Official integration guide: https://help.aliyun.com/zh/vod/developer-reference/integration
+
+## Features
+
+- Vue 3 component and plugin installation via `app.use(VueAliplayerV2, options)`.
+- TypeScript exports for props, options, events, player instances, and exposed ref methods.
+- Loads Aliyun `imp-web-player` SDK 2.37.0 by default, with custom CSS/JS URL support.
+- Supports `source` URLs, `options.source`, VID + PlayAuth, and STS credential playback.
+- Infers `mp4`, `m3u8`, `flv`, `mp3`, and `rtmp` formats from source URLs.
+- Adds an optional low-latency preset for FLV live streams.
+- Supports License config for newer Aliplayer Web SDK versions.
+- Supports multiple player instances while loading the SDK assets only once.
+- Loads extra component scripts before player initialization for playlists, watermarks, marquees, and other Aliplayer extensions.
+- Provides an optional blocker for known tracking requests.
+
+## Installation
+
+```bash
+npm install vue-aliplayer-v2
+```
+
+```bash
+yarn add vue-aliplayer-v2
+```
+
+```bash
+pnpm add vue-aliplayer-v2
+```
+
+## Quick Start
+
+### Global Registration
+
+```ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import VueAliplayerV2 from 'vue-aliplayer-v2';
+
+const app = createApp(App);
+
+app.use(VueAliplayerV2, {
+    sdkVersion: '2.37.0'
+});
+
+app.mount('#app');
+```
+
+```vue
+<template>
+    <VueAliplayerV2
+        source="//player.alicdn.com/video/aliyunmedia.mp4"
+        :options="{ autoplay: true, useH5Prism: true }"
+    />
+</template>
+```
+
+### Local Import
+
+```vue
+<template>
+    <VueAliplayerV2
+        ref="playerRef"
+        :source="source"
+        :options="options"
+        :license="license"
+        low-latency
+        @ready="handleReady"
+        @error="handleError"
+        @sdk-error="handleSdkError"
+    />
+</template>
+
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import VueAliplayerV2, {
+    type AliplayerLicense,
+    type AliplayerOptions,
+    type VueAliplayerV2Expose
+} from 'vue-aliplayer-v2';
+
+const playerRef = ref<VueAliplayerV2Expose | null>(null);
+
+const source = ref('//player.alicdn.com/video/aliyunmedia.mp4');
+
+const license = ref<AliplayerLicense | null>({
+    domain: 'example.com',
+    key: 'your-license-key'
+});
+
+const options = reactive<AliplayerOptions>({
+    autoplay: true,
+    isLive: false,
+    useH5Prism: true,
+    playsinline: true,
+    width: '100%',
+    height: '420px',
+    controlBarVisibility: 'hover'
+});
+
+function handleReady() {
+    playerRef.value?.play();
+}
+
+function handleError(error: unknown) {
+    console.log('player error', error);
+}
+
+function handleSdkError(error: Error) {
+    console.log('sdk load error', error.message);
+}
+</script>
+```
+
+## Plugin Options
+
+`app.use(VueAliplayerV2, options)` sets global defaults. Component props with the same names override these defaults per instance.
+
+```ts
+app.use(VueAliplayerV2, {
+    sdkVersion: '2.37.0',
+    cssLink: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/skins/default/aliplayer-min.css',
+    scriptSrc: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/aliplayer-min.js',
+    componentScripts: ['/aliplayer-components/watermark.js'],
+    disableTracking: false,
+    trackingUrlPatterns: ['newplayer/track']
+});
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sdkVersion` | `string` | `2.37.0` | Aliyun Web Player SDK version. Used to generate official asset URLs when `cssLink` or `scriptSrc` is not provided. |
+| `cssLink` | `string` | Official 2.37.0 CSS | Custom Aliplayer CSS URL. |
+| `scriptSrc` | `string` | Official 2.37.0 JS | Custom Aliplayer JS URL. |
+| `componentScripts` | `string[]` | `[]` | Extra component or business extension script URLs. |
+| `disableTracking` | `boolean` | `false` | Enables the known Aliplayer tracking request blocker. |
+| `trackingUrlPatterns` | `Array<string \| RegExp>` | `['newplayer/track']` | URL fragments or regular expressions to block. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` | `string \| null` | `null` | Playback source URL. It has priority over `options.source`. Same-format changes prefer `loadByUrl`; cross-format changes recreate the player. |
+| `options` | `AliplayerOptions \| null` | `null` | Raw Aliplayer initialization options. The component adds `id`, `source`, `license`, `format`, and low-latency defaults when needed. |
+| `license` | `AliplayerLicense \| null` | `null` | Aliplayer License config. It has priority over `options.license`. |
+| `autoFormat` | `boolean` | `true` | Infers `format` from `source`. |
+| `lowLatency` | `boolean` | `false` | Enables the low-latency FLV live preset. |
+| `normalizeSourceUrl` | `boolean` | `true` | Runs `encodeURI` on source URLs to handle Chinese characters, spaces, and other unencoded characters. |
+| `forbidFastForward` | `boolean` | `false` | Prevents drag-to-fast-forward behavior. |
+| `sdkVersion` | `string` | Global option | Overrides the SDK version for the current component. |
+| `cssLink` | `string` | Global option | Overrides the CSS URL for the current component. |
+| `scriptSrc` | `string` | Global option | Overrides the JS URL for the current component. |
+| `componentScripts` | `string[]` | Global option | Extra scripts to load before initializing the current component. |
+| `disableTracking` | `boolean` | Global option | Enables tracking request blocking for the current component. |
+| `trackingUrlPatterns` | `Array<string \| RegExp>` | Global option | Tracking URL rules for the current component. |
+
+## Common AliplayerOptions Fields
+
+`options` is passed through to the Aliplayer SDK, so official SDK fields can still be used. The package declares the common fields below and keeps an index signature for additional official or business fields.
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `source` | `string` | Playback source URL. |
+| `width` | `string` | Player width, for example `100%`. |
+| `height` | `string` | Player height, for example `420px`. |
+| `autoplay` | `boolean` | Whether to autoplay. |
+| `isLive` | `boolean` | Whether the stream is live. |
+| `format` | `string` | Source format, such as `mp4`, `m3u8`, or `flv`. |
+| `license` | `AliplayerLicense` | Aliplayer License config. |
+| `vid` | `string` | VOD video ID. |
+| `playauth` | `string` | VOD PlayAuth token. |
+| `authTimeout` | `number` | Playback URL validity duration in seconds. |
+| `region` | `string` | STS media region, for example `cn-shanghai`. |
+| `accessKeyId` | `string` | Temporary STS AccessKey ID. |
+| `accessKeySecret` | `string` | Temporary STS AccessKey Secret. |
+| `securityToken` | `string` | STS security token. |
+| `components` | `unknown[]` | Aliplayer custom component config. |
+| `enableStashBufferForFlv` | `boolean` | Whether FLV stash buffer is enabled. |
+| `stashInitialSizeForFlv` | `number` | FLV initial stash size. |
+| `rtsVersion` | `string` | RTS SDK version. |
+
+## Events
+
+The component forwards common Aliplayer events and adds `sdk-error`.
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `ready` | `unknown` | Player initialization completed. |
+| `play` | `unknown` | Playback started. |
+| `pause` | `unknown` | Playback paused. |
+| `canplay` | `unknown` | Media can play. |
+| `playing` | `unknown` | Media is playing. |
+| `ended` | `unknown` | Playback ended. |
+| `liveStreamStop` | `unknown` | Live stream stopped. |
+| `onM3u8Retry` | `unknown` | M3U8 retry event. |
+| `hideBar` | `unknown` | Control bar hidden. |
+| `showBar` | `unknown` | Control bar shown. |
+| `waiting` | `unknown` | Playback is waiting. |
+| `timeupdate` | `unknown` | Playback time updated. |
+| `snapshoted` | `unknown` | Snapshot completed. |
+| `requestFullScreen` | `unknown` | Fullscreen requested. |
+| `cancelFullScreen` | `unknown` | Fullscreen canceled. |
+| `error` | `unknown` | Runtime player error. |
+| `startSeek` | `unknown` | Seek started. |
+| `completeSeek` | `unknown` | Seek completed. |
+| `sdk-error` | `Error` | SDK CSS, JS, or extension script failed to load. |
+
+## Ref Methods
+
+Use `ref<VueAliplayerV2Expose | null>` to access exposed methods.
+
+```ts
+playerRef.value?.play();
+playerRef.value?.pause();
+playerRef.value?.seek(30);
+playerRef.value?.setVolume(0.8);
+playerRef.value?.loadByUrl('//player.alicdn.com/video/aliyunmedia.mp4');
+playerRef.value?.requestFullScreen();
+playerRef.value?.retry();
+```
+
+| Method | Description |
+| --- | --- |
+| `getPlayer()` | Returns the underlying Aliplayer instance. |
+| `init()` | Loads the SDK and initializes the player. |
+| `initPlayer()` | Creates a player instance with current props/options. |
+| `reload(nextSource?)` | Reloads the player, optionally with a new source. |
+| `retry(nextSource?)` | Business-friendly retry method after playback failure. |
+| `play()` | Starts playback. |
+| `pause()` | Pauses playback. |
+| `replay()` | Replays from the beginning. |
+| `seek(time)` | Seeks to a time in seconds. |
+| `getCurrentTime()` | Returns current playback time. |
+| `getDuration()` | Returns media duration. |
+| `getVolume()` | Returns current volume. |
+| `setVolume(volume)` | Sets volume. |
+| `loadByUrl(url, time?)` | Switches source by URL. |
+| `replayByVidAndPlayAuth(vid, playauth)` | Replays with VID + PlayAuth. |
+| `replayByVidAndAuthInfo(...)` | Replays with MPS auth info. |
+| `setPlayerSize(width, height)` | Sets player size. |
+| `setSpeed(speed)` | Sets playback speed. |
+| `setSanpshotProperties(width, height, rate)` | Sets snapshot options. The method name follows the SDK spelling. |
+| `requestFullScreen()` | Enters fullscreen. |
+| `cancelFullScreen()` | Exits fullscreen. |
+| `getIsFullScreen()` | Returns fullscreen state. |
+| `getStatus()` | Returns player status. |
+| `setLiveTimeRange(beginTime, endTime)` | Sets the playable live time-shift range. |
+| `setRotate(rotate)` | Sets video rotation. |
+| `getRotate()` | Returns video rotation. |
+| `setImage(image)` | Sets video mirror mode. |
+| `dispose()` | Disposes the player. |
+| `setCover(cover)` | Sets cover image. |
+| `setProgressMarkers(markers)` | Sets progress markers. |
+| `setPreviewTime(time)` | Sets preview duration. |
+| `getPreviewTime()` | Returns preview duration. |
+| `isPreview()` | Returns whether the player is in preview mode. |
+| `off(eventName, handler)` | Removes a listener from the underlying player. |
+
+## Usage Examples
+
+### URL Playback
+
+```vue
+<VueAliplayerV2
+    source="//player.alicdn.com/video/aliyunmedia.mp4"
+    :options="{
+        autoplay: true,
+        useH5Prism: true,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+### VID + PlayAuth
+
+```vue
+<VueAliplayerV2
+    :options="{
+        vid: '<your-video-id>',
+        playauth: '<your-playauth>',
+        authTimeout: 7200,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+`VID + PlayAuth` is an initialization mode, so `source` is not required. To switch after the player has been created, call:
+
+```ts
+playerRef.value?.replayByVidAndPlayAuth(vid, playauth);
+```
+
+### STS
+
+```vue
+<VueAliplayerV2
+    :options="{
+        vid: '<your-video-id>',
+        region: 'cn-shanghai',
+        accessKeyId: '<temporary-access-key-id>',
+        accessKeySecret: '<temporary-access-key-secret>',
+        securityToken: '<temporary-security-token>',
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+### FLV Live and Low Latency
+
+```vue
+<VueAliplayerV2
+    source="//example.com/live.flv"
+    low-latency
+    :options="{
+        isLive: true,
+        autoplay: true,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+When `low-latency` is enabled and the current source is FLV with `options.isLive = true`, the component adds:
+
+```ts
+{
+    enableStashBufferForFlv: false,
+    stashInitialSizeForFlv: 128
+}
+```
+
+You can override these values directly in `options`.
+
+### Live Time Shift
+
+```ts
+playerRef.value?.setLiveTimeRange('2026/05/23 10:00:00', '2026/05/23 12:00:00');
+```
+
+You can also pass official time-shift options during initialization:
+
+```vue
+<VueAliplayerV2
+    source="//example.com/live.m3u8"
+    :options="{
+        isLive: true,
+        liveStartTime: '2026/05/23 10:00:00',
+        liveOverTime: '2026/05/23 12:00:00'
+    }"
+/>
+```
+
+### Multiple Players
+
+```vue
+<template>
+    <VueAliplayerV2
+        v-for="item in sources"
+        :key="item"
+        :source="item"
+        :options="options"
+    />
+</template>
+
+<script setup lang="ts">
+import { reactive } from 'vue';
+
+const sources = [
+    '//player.alicdn.com/video/aliyunmedia.mp4',
+    '//yunqivedio.alicdn.com/user-upload/nXPDX8AASx.mp4'
+];
+
+const options = reactive({
+    autoplay: false,
+    width: '100%',
+    height: '300px'
+});
+</script>
+```
+
+v2 reuses SDK CSS/JS loading promises, so multiple players do not insert duplicate SDK tags for the same assets.
+
+### Custom Components and Marquees
+
+Aliplayer custom components often require extra scripts. Use `componentScripts` to load extension scripts before player initialization.
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    :component-scripts="['/aliplayer-components/marquee.js']"
+    :options="{
+        components: [
+            {
+                name: 'MarqueeComponent',
+                type: window.MarqueeComponent,
+                args: {
+                    text: 'vue-aliplayer-v2'
+                }
+            }
+        ]
+    }"
+/>
+```
+
+Playlist, watermark, marquee, and similar features depend on the Aliplayer custom component scripts you provide.
+
+### Forbid Fast Forward
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    forbid-fast-forward
+/>
+```
+
+This is implemented by watching playback progress and seeking back when a forward jump is detected. It is useful as a lightweight business restriction. Stronger anti-bypass requirements should be combined with server-side authorization, preview limits, or encrypted playback.
+
+### Retry After Failure
+
+Aliplayer error pages are rendered by the SDK itself. Business code can listen to `error` and call `retry()` or `reload()` for local recovery.
+
+```ts
+function handleError() {
+    playerRef.value?.retry();
+}
+```
+
+### Optional Tracking Request Blocking
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    disable-tracking
+    :tracking-url-patterns="['newplayer/track', /\/logstores\//]"
+/>
+```
+
+This only blocks URLs matching the configured rules and is intended as a wrapper-level fallback. In production, prefer official Aliyun settings, console-side configuration, or your own compliant analytics strategy.
+
+## SSR and Nuxt
+
+The Aliplayer SDK depends on browser `window` and DOM APIs. In SSR projects, render the player only on the client. For Nuxt:
+
+```vue
+<ClientOnly>
+    <VueAliplayerV2 :source="source" />
+</ClientOnly>
+```
+
+## TypeScript
+
+The package entry exports these types:
+
+```ts
+import type {
+    AliplayerEventName,
+    AliplayerInstance,
+    AliplayerLicense,
+    AliplayerOptions,
+    AliplayerV2Props,
+    VueAliplayerV2Expose,
+    VueAliplayerV2Options
+} from 'vue-aliplayer-v2';
+```
+
+## Migration
+
+### From 1.x to 2.x
+
+- v2 supports Vue 3 only and no longer keeps Vue 2 compatibility.
+- The build toolchain is Vite, with ESM and UMD library outputs.
+- Global registration now uses Vue 3 `app.use(VueAliplayerV2, options)`.
+- Component refs should use `ref<VueAliplayerV2Expose | null>`.
+- The default SDK path now uses Aliyun `imp-web-player` 2.37.0.
+- New configs include `license`, `lowLatency`, `normalizeSourceUrl`, `componentScripts`, and `disableTracking`.
+- For legacy Vue 2 projects, pin `vue-aliplayer-v2@1.x`.
+
+## FAQ
+
+### The player is not visible
+
+Make sure the player is rendered only in the browser and check the `sdk-error` event. Common causes include blocked SDK assets, missing License config, source CORS issues, and a container height of `0`.
+
+### The new SDK reports a License error
+
+Apply for a Web Player License in the Aliyun console and pass it through the `license` prop or `options.license`:
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    :license="{ domain: 'example.com', key: 'your-license-key' }"
+/>
+```
+
+### URLs with Chinese characters or spaces fail to play
+
+`normalizeSourceUrl = true` runs `encodeURI` on source URLs by default. If your business code already encodes URLs, disable it explicitly:
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    :normalize-source-url="false"
+/>
+```
+
+### Should I update `source` or call `loadByUrl` when switching sources?
+
+For normal Vue usage, update `source`. The component handles same-format and cross-format changes. For imperative workflows, call `playerRef.value?.loadByUrl(url)`.
+
+## Local Development
+
+```bash
+npm install
+npm run dev
+```
+
+Type check:
+
+```bash
+npm run type-check
+```
+
+Build the demo:
+
+```bash
+npm run build
+```
+
+Build the library:
+
+```bash
+npm run lib
+```
+
+## License
+
+[MIT](./LICENSE)
--- a/README.md
+++ b/README.md
@ -1,512 +1,551 @@
-# vue-alipayer-v2
+# vue-aliplayer-v2

-## 感谢每一位支持开源的朋友. 这是一个基于 Alipayer 开发并封装成 vue 组件的播放器.
+[English](./README.en-US.md) | 简体中文

-### vue 中使用 Alipayer,播放 rtmp,m3u8,mp4 视频
+基于阿里云 Web 播放器 Aliplayer SDK 的 Vue 3 播放器组件。v2 使用 Vue 3、TypeScript 和 Vite 重构，支持 URL 播放、VID + PlayAuth、STS、直播、低延迟 FLV、自动格式推断、License 注入、扩展组件脚本、多实例和常用播放器实例方法。

-#### [本项目在线演示](https://langyuxiansheng.github.io/vue-aliplayer-v2/)
+> v2 不再兼容 Vue 2。Vue 2 项目请继续安装 `vue-aliplayer-v2@1.x`。

-#### [阿里云播放器在线演示](https://player.alicdn.com/aliplayer/index.html)
+## 在线演示

-> 假如此轮子对你有帮助,请顺手 star 一下吧.o(_￣︶￣_)o
+- 项目 demo：https://langyuxiansheng.github.io/vue-aliplayer-v2/
+- 阿里云播放器官方演示：https://player.alicdn.com/aliplayer/index.html
+- 阿里云播放器接入文档：https://help.aliyun.com/zh/vod/developer-reference/integration

-## 1.安装使用! 下载安装 npm 包
+## 特性
+
+- Vue 3 组件和插件安装方式，支持 `app.use(VueAliplayerV2, options)`。
+- TypeScript 类型导出，包含 props、options、事件、播放器实例和 ref 暴露方法。
+- 默认加载阿里云 `imp-web-player` SDK 2.37.0，也可以自定义 CSS/JS 地址。
+- 支持 `source` URL、`options.source`、VID + PlayAuth、STS 鉴权配置。
+- 自动识别 `mp4`、`m3u8`、`flv`、`mp3`、`rtmp` 播放格式。
+- FLV 直播低延迟预设，可按业务需要覆盖 stash buffer 配置。
+- 支持 License 配置，适配新版 Aliplayer Web 播放器要求。
+- 支持多播放器共存，SDK 资源只加载一次。
+- 支持额外加载自定义组件脚本，便于接入播放列表、水印、跑马灯等 Aliplayer 扩展。
+- 提供可选的已知 track 上报拦截能力。
+
+## 安装
+
+```bash
+npm install vue-aliplayer-v2
+```

 ```bash
-npm i vue-aliplayer-v2 --save
-or
 yarn add vue-aliplayer-v2
 ```

-#### 全局注册 main.js
-
-```javascript
-import VueAliplayerV2 from "vue-aliplayer-v2";
-
-Vue.use(VueAliplayerV2);
-
-//可选全局配置
-//Vue.use(VueAliplayerV2,{
-// cssLink: 'https://g.alicdn.com/de/prismplayer/2.8.2/skins/default/aliplayer-min.css',
-// scriptSrc: 'https://g.alicdn.com/de/prismplayer/2.8.2/aliplayer-min.js'
-//});
+```bash
+pnpm add vue-aliplayer-v2
 ```

-#### 局部注册 App.vue
+## 快速开始

-```javascript
-//推荐第一种(仅v1.2.3)及以上的版本可用
-import VueAliplayerV2 from "vue-aliplayer-v2";
-components: {
-  VueAliplayerV2;
-}
+### 全局注册

-//或者
-components: {
-  VueAliplayerV2: VueAliplayerV2.Player;
-}
+```ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import VueAliplayerV2 from 'vue-aliplayer-v2';
+
+const app = createApp(App);
+
+app.use(VueAliplayerV2, {
+    sdkVersion: '2.37.0'
+});
+
+app.mount('#app');
 ```

-## 2.组件中使用
-
-### 组件模板使用,下面的视频连接仅供演示测试.
-
-```html
+```vue
 <template>
-  <div id="app">
-    <template v-if="!isShowMultiple && show">
-      <vue-aliplayer-v2
-        :source="source"
-        ref="VueAliplayerV2"
-        :options="options"
+    <VueAliplayerV2
+        source="//player.alicdn.com/video/aliyunmedia.mp4"
+        :options="{ autoplay: true, useH5Prism: true }"
    />
-    </template>
-    <div v-if="isShowMultiple && show" class="show-multiple">
-      <template v-for="x in 5">
-        <vue-aliplayer-v2
-          class="multiple-player"
-          :key="x"
-          :source="source"
-          ref="VueAliplayerV2"
-          :options="options"
-        />
-      </template>
-    </div>
-    <p class="remove-text" v-if="!show">播放器已销毁!</p>
-    <div class="player-btns">
-      <template v-if="!isShowMultiple && show">
-        <span @click="play()">播放</span>
-        <span @click="pause()">暂停</span>
-        <span @click="replay()">重播</span>
-        <span @click="getCurrentTime()">播放时刻</span>
-        <span @click="getStatus()">获取播放器状态</span>
-      </template>
-      <span @click="show = !show">{{ show ? '销毁' : '重载' }}</span>
-      <span @click="options.isLive = !options.isLive"
-        >{{ options.isLive ? '切换普通模式' : '切换直播模式' }}</span
-      >
-      <span @click="showMultiple()"
-        >{{isShowMultiple ? '显示1个播放器' : '显示多个播放器'}}</span
-      >
-    </div>
-    <div class="source-box">
-      <span class="source-label">选择播放源(支持动态切换):</span>
-      <select v-model="source" name="source" id="source">
-        <option value="//player.alicdn.com/video/aliyunmedia.mp4"
-          >播放源1</option
-        >
-        <option value="//yunqivedio.alicdn.com/user-upload/nXPDX8AASx.mp4"
-          >播放源2</option
-        >
-        <option
-          value="//tbm-auth.alicdn.com/e7qHgLdugbzzKh2eW0J/kXTgBkjvNXcERYxh2PA@@hd_hq.mp4?auth_key=1584519814-0-0-fc98b2738f331ff015f7bf5c62394888"
-          >播放源3</option
-        >
-        <option value="//ivi.bupt.edu.cn/hls/cctv1.m3u8">直播播放源4</option>
-      </select>
-    </div>
-    <div class="source-box">
-      <span class="source-label">输入播放源(支持动态切换):</span>
-      <input class="source-input" type="text" v-model="source" />
-    </div>
-  </div>
 </template>
-<script>
-  export default {
-    data() {
-      return {
-        options: {
-          // source:'//player.alicdn.com/video/aliyunmedia.mp4',
-          isLive: true, //切换为直播流的时候必填
-          // format: 'm3u8'  //切换为直播流的时候必填
-        },
-        source: "//player.alicdn.com/video/aliyunmedia.mp4",
-        // source: '//ivi.bupt.edu.cn/hls/cctv1.m3u8',
-        show: true,
-        isShowMultiple: false,
-      };
-    },
-
-    methods: {
-      play() {
-        this.$refs.VueAliplayerV2.play();
-      },
-
-      pause() {
-        this.$refs.VueAliplayerV2.pause();
-      },
-
-      replay() {
-        this.$refs.VueAliplayerV2.replay();
-      },
-
-      getCurrentTime() {
-        // this.$refs.VueAliplayerV2.getCurrentTime();
-        this.source = "http://ivi.bupt.edu.cn/hls/cctv1.m3u8";
-      },
-
-      getStatus() {
-        const status = this.$refs.VueAliplayerV2.getStatus();
-        console.log(`getStatus:`, status);
-        alert(`getStatus:${status}`);
-      },
-
-      showMultiple() {
-        this.isShowMultiple = !this.isShowMultiple;
-      },
-    },
-  };
-</script>
-<style lang="less">
-  * {
-    margin: 0;
-    padding: 0;
-  }
-  .remove-text {
-    text-align: center;
-    padding: 20px;
-    font-size: 24px;
-  }
-  .show-multiple {
-    display: flex;
-    .multiple-player {
-      width: calc(100% / 4);
-      margin: 20px;
-    }
-  }
-  .player-btns {
-    width: 100%;
-    display: flex;
-    justify-content: center;
-    flex-wrap: wrap;
-    span {
-      margin: 0 auto;
-      display: inline-block;
-      padding: 5px 10px;
-      width: 150px;
-      height: 40px;
-      line-height: 40px;
-      border: 1px solid #eee;
-      background: #e1e1e1;
-      border-radius: 10px;
-      text-align: center;
-      margin: 5px;
-      cursor: pointer;
-    }
-  }
-  .source-box {
-    padding: 5px 10px;
-    margin-bottom: 20px;
-    .source-label {
-      margin-right: 20px;
-      font-size: 16px;
-      display: block;
-    }
-    #source {
-      margin-top: 10px;
-    }
-    .source-input {
-      margin-top: 10px;
-      padding: 5px 10px;
-      width: 80%;
-      border: 1px solid #ccc;
-    }
-  }
-</style>
 ```

-## 3.功能与配置
+### 局部引入

-```javascript
-props:{
+```vue
+<template>
+    <VueAliplayerV2
+        ref="playerRef"
+        :source="source"
+        :options="options"
+        :license="license"
+        low-latency
+        @ready="handleReady"
+        @error="handleError"
+        @sdk-error="handleSdkError"
+    />
+</template>

-    forbidFastForward: {    //禁止拖拽快进
-            required: false,
-            type: [Boolean],
-            default: false
-    },
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import VueAliplayerV2, {
+    type AliplayerLicense,
+    type AliplayerOptions,
+    type VueAliplayerV2Expose
+} from 'vue-aliplayer-v2';

-    options: {  //配置项 (options.source 不支持动态切换,需要动态切换请直接使用source)
-        required: false,
-        type: [Object],
-        default: () => null
-    },
+const playerRef = ref<VueAliplayerV2Expose | null>(null);

-    source: {  //播放源(此属性存在则优先于options.source) 支持动态切换,目前只支持同种格式（mp4/flv/m3u8）之间切换。暂不支持直播rtmp流切换。
-        required: false,
-        type: [Object],
-        default: () => null
-    },
+const source = ref('//player.alicdn.com/video/aliyunmedia.mp4');

-    cssLink:{   //css版本源
-        required: false,
-        type: [String],
-        default: `https://g.alicdn.com/de/prismplayer/2.9.7/skins/default/aliplayer-min.css`
-    },
-    scriptSrc:{ //js版本源
-        required: false,
-        type: [String],
-        default: `https://g.alicdn.com/de/prismplayer/2.9.7/aliplayer-min.js`
-    }
+const license = ref<AliplayerLicense | null>({
+    domain: 'example.com',
+    key: 'your-license-key'
+});
+
+const options = reactive<AliplayerOptions>({
+    autoplay: true,
+    isLive: false,
+    useH5Prism: true,
+    playsinline: true,
+    width: '100%',
+    height: '420px',
+    controlBarVisibility: 'hover'
+});
+
+function handleReady() {
+    playerRef.value?.play();
 }
+
+function handleError(error: unknown) {
+    console.log('player error', error);
+}
+
+function handleSdkError(error: Error) {
+    console.log('sdk load error', error.message);
+}
+</script>
 ```

-### 3.1 配置项 options 属性
+## Vue 插件配置

-可以参考 [属性和接口说明](https://help.aliyun.com/document_detail/125572.html?spm=a2c4g.11186623.6.1085.36fc6fc57WKZ5P)
+`app.use(VueAliplayerV2, options)` 会设置全局默认值。单个组件传入同名 prop 时，会覆盖全局默认值。
+
+```ts
+app.use(VueAliplayerV2, {
+    sdkVersion: '2.37.0',
+    cssLink: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/skins/default/aliplayer-min.css',
+    scriptSrc: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/aliplayer-min.js',
+    componentScripts: ['/aliplayer-components/watermark.js'],
+    disableTracking: false,
+    trackingUrlPatterns: ['newplayer/track']
+});
+```
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `sdkVersion` | `string` | `2.37.0` | 阿里云 Web 播放器 SDK 版本。未传 `cssLink` 或 `scriptSrc` 时用于生成官方资源地址。 |
+| `cssLink` | `string` | 2.37.0 官方 CSS | 自定义 Aliplayer CSS 地址。 |
+| `scriptSrc` | `string` | 2.37.0 官方 JS | 自定义 Aliplayer JS 地址。 |
+| `componentScripts` | `string[]` | `[]` | 自定义组件或业务扩展脚本地址列表。 |
+| `disableTracking` | `boolean` | `false` | 是否启用已知 Aliplayer 统计上报拦截。 |
+| `trackingUrlPatterns` | `Array<string \| RegExp>` | `['newplayer/track']` | 需要拦截的统计上报 URL 片段或正则。 |
+
+## Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `source` | `string \| null` | `null` | 播放源 URL。存在时优先于 `options.source`。同格式变更优先调用 `loadByUrl`，跨格式变更会重建播放器。 |
+| `options` | `AliplayerOptions \| null` | `null` | 透传给 Aliplayer 的初始化配置。组件会补充 `id`、`source`、`license`、`format` 和低延迟默认值。 |
+| `license` | `AliplayerLicense \| null` | `null` | Aliplayer License 配置，优先级高于 `options.license`。 |
+| `autoFormat` | `boolean` | `true` | 是否根据 `source` 自动推断 `format`。 |
+| `lowLatency` | `boolean` | `false` | 是否启用 FLV 直播低延迟预设。 |
+| `normalizeSourceUrl` | `boolean` | `true` | 是否对播放源执行 `encodeURI`，用于处理中文、空格等未编码地址。 |
+| `forbidFastForward` | `boolean` | `false` | 是否禁止拖拽快进。 |
+| `sdkVersion` | `string` | 全局配置 | 覆盖当前组件使用的 SDK 版本。 |
+| `cssLink` | `string` | 全局配置 | 覆盖当前组件使用的 CSS 地址。 |
+| `scriptSrc` | `string` | 全局配置 | 覆盖当前组件使用的 JS 地址。 |
+| `componentScripts` | `string[]` | 全局配置 | 当前组件初始化前需要加载的扩展脚本。 |
+| `disableTracking` | `boolean` | 全局配置 | 当前组件是否启用 track 拦截。 |
+| `trackingUrlPatterns` | `Array<string \| RegExp>` | 全局配置 | 当前组件的 track 拦截规则。 |
+
+## AliplayerOptions 常用字段
+
+`options` 会完整透传给 Aliplayer SDK，因此可以继续使用官方文档中的配置项。组件类型中内置了以下常用字段，并保留索引签名支持官方新增字段。

 | 名称 | 类型 | 说明 |
-| :----------------------- | :-----------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| source                   |    String     | 视频播放地址 url：单独 url。默认状态，表示使用 vid+playauth。source 播放方式优先级最高。source 支持多清晰度设置：source:’{“HD”:”address1”,”SD”:”address2”’，详情参见多清晰度播放。 |
-| vid                      |    String     | 媒体转码服务的媒体 Id。                                                                                                                                                            |
-| playauth                 |    String     | 播放权证，如何得到参见获取 playauth。                                                                                                                                              |
-| height                   |    String     | 播放器高度，可形如‘100%’或者‘100px’,chrome 浏览器下 flash 播放器分别不能小于 397x297。                                                                                             |
-| width                    |    String     | 播放器宽度，可形如‘100%’或者‘100px’,chrome 浏览器下 flash 播放器分别不能小于 397x297。                                                                                             |
-| videoWidth               |    String     | 视频宽度，仅 h5 支持。详情参见旋转和镜像。                                                                                                                                         |
-| videoHeight              |    String     | 视频高度，仅 h5 支持。详情参见旋转和镜像。                                                                                                                                         |
-| preload                  |    Boolean    | 播放器自动加载，目前仅 h5 可用。                                                                                                                                                   |
-| cover                    |    String     | 播放器默认封面图片，请填写正确的图片 url 地址。需要 autoplay 为’false’时，才生效。Flash 播放器封面也需要开启允许跨域访问。                                                         |
-| isLive                   |    Boolean    | 播放内容是否为直播，直播时会禁止用户拖动进度条。                                                                                                                                   |
-| autoplay                 |    Boolean    | 播放器是否自动播放，在移动端 autoplay 属性会失效。Safari11 不会自动开启自动播放如何开启。                                                                                          |
-| rePlay                   |    Boolean    | 播放器自动循环播放。                                                                                                                                                               |
-| useH5Prism               |    Boolean    | 指定使用 H5 播放器。                                                                                                                                                               |
-| useFlashPrism            |    Boolean    | 指定使用 Flash 播放器。                                                                                                                                                            |
-| playsinline              |    Boolean    | H5 是否内置播放，有的 Android 浏览器不起作用。                                                                                                                                     |
-| showBuffer               |    Boolean    | 显示播放时缓冲图标，默认 true。                                                                                                                                                    |
-| skinRes                  |      Url      | 说明：皮肤图片，不建议随意修改该字段，如要修改，请参照皮肤定制。                                                                                                                   |
-| skinLayout               | Array Boolean | 说明：功能组件布局配置，不传该字段使用默认布局。传 false 隐藏所有功能组件，请参照皮肤定制。                                                                                        |
-| controlBarVisibility     |    String     | 控制面板的实现，默认为‘hover’。可选的值为：‘click’、‘hover’、‘always’。                                                                                                            |
-| showBarTime              |    String     | 控制栏自动隐藏时间（ms）。                                                                                                                                                         |
-| extraInfo                |    String     | 说明：JSON 串用于定制性接口参数。                                                                                                                                                  |
-| >                        |       >       | 1.“fullTitle”：“测试页面”全屏时显示视频标题（仅 flash 支持）。                                                                                                                     |
-| >                        |       >       | 2. “m3u8BufferLength”：“30”播放 m3u8 时加载缓存 ts 文件长度单位（秒）（仅 flash 支持）。                                                                                           |
-| >                        |       >       | 3. “liveStartTime”：“2016/08/17 12:00:00”,直播开始时间，用于提示直播未开始(仅 flash 支持)。                                                                                        |
-| >                        |       >       | 4. “liveOverTime”：“2016/08/17 14:00:00”,直播结束时间，用于提示直播结束（仅 flash 支持）。                                                                                         |
-| enableSystemMenu         |    Boolean    | 是否允许系统右键菜单显示，默认为 false。                                                                                                                                           |
-| format                   |    String     | 指定播放地址格式，只有使用 vid 的播放方式时支持,可选值为’mp4’、’m3u8’、’flv’、’mp3’，默认为空，仅 H5 支持。                                                                        |
-| mediaType                |    String     | 指定返回音频还是视频，只有使用 vid 的播放方式时支持。可选值为’video’和’audio’，默认为’video’,‘audio’主要是针对只包含音频的视频格式，比如音频的 mp4，仅 H5 支持。                   |
-| qualitySort              |    String     | 指定排序方式，只有使用 vid + plauth 播放方式时支持。‘desc’表示按倒序排序（即：从大到小排序）,‘asc’表示按正序排序（即：从小到大排序）,默认值：‘asc’，仅 H5 支持。                   |
-| definition               |    String     | 显示视频清晰度，多个用逗号分隔，比如：’FD,LD’，此值是 vid 对应流清晰度的一个子集，取值范围：FD（流畅）LD（标清）SD（高清）HD（超清）OD（原画）2K（2K）4K（4K），仅 H5 支持。       |
-| defaultDefinition        |    String     | 默认视频清晰度，此值是 vid 对应流的一个清晰度，取值范围：FD（流畅）LD（标清）SD（高清）HD（超清）OD（原画）2K（2K）4K（4K）,仅 H5 支持。                                           |
-| x5_type                  |    String     | 声明启用同层 H5 播放器，启用时设置的值为‘h5’,详情参见同层播放。                                                                                                                    |
-| x5_fullscreen            |    Boolean    | 声明视频播放时是否进入到 TBS 的全屏模式，默认为 false。当需要把视频做为背景时，设置为 true,详情参见同层播放。                                                                      |
-| x5_video_position        |    String     | 声明视频播在界面上的位置，默认为“center”。可选值为：“top”，“center”,详情参见同层播放。                                                                                             |
-| x5_orientation           |    String     | 声明 TBS 播放器支持的方向，可选值：landscape：横屏,portraint：竖屏,详情参见同层播放。                                                                                              |
-| x5LandscapeAsFullScreen  |    String     | 声明 TBS 全屏播放是否横屏，默认值为 true。                                                                                                                                         |
-| autoPlayDelay            |    Number     | 延迟播放时间，单位为秒。详情参见延迟播放                                                                                                                                           |
-| autoPlayDelayDisplayText |    String     | 延迟播放提示文本，详情参见延迟播放。                                                                                                                                               |
-| language                 |    String     | 国际化，默认为‘zh-cn’。如果未设置，则采用浏览器语言。可选值为‘zh-cn’、‘en-us’或其它值。                                                                                            |
-| languageTexts            |     JSON      | 自定义国际化文本 json 结构，key 的值需要和 language 属性值对应起来。例子：{jp:{Play:”Play”}},自定义值参见 Json 结构。                                                              |
-| snapshot                 |    Boolean    | flash 启用截图功能。                                                                                                                                                               |
-| snapshotWatermark        |    Object     | H5 设置截图水印。                                                                                                                                                                  |
-| useHlsPluginForSafari    |    Boolean    | Safari 浏览器可以启用 Hls 插件播放，Safari 11 除外。                                                                                                                               |
-| enableStashBufferForFlv  |    Boolean    | H5 播放 flv 时，设置是否启用播放缓存，只在直播下起作用。                                                                                                                           |
-| stashInitialSizeForFlv   |    Number     | H5 播放 flv 时，初始缓存大小，只在直播下起作用。                                                                                                                                   |
-| loadDataTimeout          |    Number     | 缓冲多长时间后，提示用户切换低清晰度，默认：20 秒。                                                                                                                                |
-| waitingTimeout           |    Number     | 最大缓冲超时时间，超过这个时间会有错误提示，默认：60 秒。                                                                                                                          |
-| liveStartTime            |    String     | 直播开始时间，直播时移功能使用，格式为：“2018/01/04 12:00:00”。                                                                                                                    |
-| liveOverTime             |    String     | 直播结束时间，直播时移功能使用，格式为：“2018/01/04 12:00:00”。                                                                                                                    |
-| liveTimeShiftUrl         |    String     | 直播可用时移查询地址，详情参见直播时移。                                                                                                                                           |
-| liveShiftSource          |    String     | flv 直播地址播放时，hls 的流地址，详情参见直播时移。                                                                                                                               |
-| recreatePlayer           |   Function    | flv 直播和 hls 时移切换是，重新创建播放器方法，详情参见直播时移。                                                                                                                  |
-| diagnosisButtonVisible   |    Boolean    | 是否显示检测按钮，默认为 true。                                                                                                                                                    |
-| disableSeek              |    Boolean    | 禁用进度条的 Seek，默认为 false，仅 Flash 支持。                                                                                                                                   |
-| encryptType              |      int      | 加密类型，播放点播私有加密视频时，设置值为 1，默认值为 0。                                                                                                                         |
-| progressMarkers          |     Array     | 进度条打点内容数组，详情参见进度条打点。                                                                                                                                           |
-| vodRetry                 |      int      | 点播失败重试次数，默认 3 次                                                                                                                                                        |
-| liveRetry                |      int      | 直播播放失败重试次数，默认 5 次                                                                                                                                                    |
+| --- | --- | --- |
+| `source` | `string` | 播放源 URL。 |
+| `width` | `string` | 播放器宽度，例如 `100%`。 |
+| `height` | `string` | 播放器高度，例如 `420px`。 |
+| `autoplay` | `boolean` | 是否自动播放。 |
+| `isLive` | `boolean` | 是否为直播。 |
+| `format` | `string` | 播放格式，例如 `mp4`、`m3u8`、`flv`。 |
+| `license` | `AliplayerLicense` | Aliplayer License 配置。 |
+| `vid` | `string` | 点播视频 ID。 |
+| `playauth` | `string` | 点播播放凭证。 |
+| `authTimeout` | `number` | 播放地址有效时长，单位秒。 |
+| `region` | `string` | STS 媒资地域，例如 `cn-shanghai`。 |
+| `accessKeyId` | `string` | STS 临时 AccessKey ID。 |
+| `accessKeySecret` | `string` | STS 临时 AccessKey Secret。 |
+| `securityToken` | `string` | STS 安全令牌。 |
+| `components` | `unknown[]` | Aliplayer 自定义组件配置。 |
+| `enableStashBufferForFlv` | `boolean` | FLV 是否启用 stash buffer。 |
+| `stashInitialSizeForFlv` | `number` | FLV 初始缓存大小。 |
+| `rtsVersion` | `string` | RTS SDK 版本。 |

-### 3.2 播放器方法
+## 事件

-```javascript
-// 暂停播放
-this.$refs.VueAliplayerV2.pause();
+组件会透传常用 Aliplayer 事件，并额外提供 `sdk-error`。
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `unknown` | 播放器初始化完成。 |
+| `play` | `unknown` | 开始播放。 |
+| `pause` | `unknown` | 暂停播放。 |
+| `canplay` | `unknown` | 可以播放。 |
+| `playing` | `unknown` | 正在播放。 |
+| `ended` | `unknown` | 播放结束。 |
+| `liveStreamStop` | `unknown` | 直播流停止。 |
+| `onM3u8Retry` | `unknown` | M3U8 重试事件。 |
+| `hideBar` | `unknown` | 控制栏隐藏。 |
+| `showBar` | `unknown` | 控制栏显示。 |
+| `waiting` | `unknown` | 播放等待。 |
+| `timeupdate` | `unknown` | 播放进度更新。 |
+| `snapshoted` | `unknown` | 截图完成。 |
+| `requestFullScreen` | `unknown` | 进入全屏。 |
+| `cancelFullScreen` | `unknown` | 退出全屏。 |
+| `error` | `unknown` | 播放器运行时错误。 |
+| `startSeek` | `unknown` | 开始 seek。 |
+| `completeSeek` | `unknown` | seek 完成。 |
+| `sdk-error` | `Error` | SDK CSS、JS 或扩展脚本加载失败。 |
+
+## Ref 方法
+
+通过 `ref<VueAliplayerV2Expose | null>` 可以访问组件暴露的方法。
+
+```ts
+playerRef.value?.play();
+playerRef.value?.pause();
+playerRef.value?.seek(30);
+playerRef.value?.setVolume(0.8);
+playerRef.value?.loadByUrl('//player.alicdn.com/video/aliyunmedia.mp4');
+playerRef.value?.requestFullScreen();
+playerRef.value?.retry();
 ```

-可以参考 [播放器接口方法](https://help.aliyun.com/document_detail/125572.html?spm=a2c4g.11186623.6.1085.36fc6fc57WKZ5P#h2-u64ADu653Eu5668u63A5u53E32)
+| 方法 | 说明 |
+| --- | --- |
+| `getPlayer()` | 获取底层 Aliplayer 实例。 |
+| `init()` | 加载 SDK 并初始化播放器。 |
+| `initPlayer()` | 使用当前 props/options 创建播放器实例。 |
+| `reload(nextSource?)` | 重载播放器，可传入新的播放源。 |
+| `retry(nextSource?)` | 播放失败后的业务重试入口。 |
+| `play()` | 播放。 |
+| `pause()` | 暂停。 |
+| `replay()` | 从头重播。 |
+| `seek(time)` | 跳转到指定秒数。 |
+| `getCurrentTime()` | 获取当前播放时间。 |
+| `getDuration()` | 获取视频总时长。 |
+| `getVolume()` | 获取音量。 |
+| `setVolume(volume)` | 设置音量。 |
+| `loadByUrl(url, time?)` | 使用 URL 切换播放源。 |
+| `replayByVidAndPlayAuth(vid, playauth)` | 使用 VID + PlayAuth 重新播放。 |
+| `replayByVidAndAuthInfo(...)` | 使用 MPS 鉴权信息重新播放。 |
+| `setPlayerSize(width, height)` | 设置播放器尺寸。 |
+| `setSpeed(speed)` | 设置播放倍速。 |
+| `setSanpshotProperties(width, height, rate)` | 设置截图参数。方法名沿用阿里云 SDK 拼写。 |
+| `requestFullScreen()` | 进入全屏。 |
+| `cancelFullScreen()` | 退出全屏。 |
+| `getIsFullScreen()` | 获取是否处于全屏。 |
+| `getStatus()` | 获取播放器状态。 |
+| `setLiveTimeRange(beginTime, endTime)` | 设置直播时移可播放范围。 |
+| `setRotate(rotate)` | 设置视频旋转角度。 |
+| `getRotate()` | 获取视频旋转角度。 |
+| `setImage(image)` | 设置视频镜像。 |
+| `dispose()` | 销毁播放器。 |
+| `setCover(cover)` | 设置封面图。 |
+| `setProgressMarkers(markers)` | 设置进度条打点。 |
+| `setPreviewTime(time)` | 设置试看时间。 |
+| `getPreviewTime()` | 获取试看时间。 |
+| `isPreview()` | 判断是否处于试看状态。 |
+| `off(eventName, handler)` | 取消监听底层播放器事件。 |

-| 名称                   | 参数                                                                                  | 说明                                                                                                                                                                  |
-| :--------------------- | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| play                   | -                                                                                     | 播放视频。                                                                                                                                                            |
-| pause                  | -                                                                                     | 暂停视频。                                                                                                                                                            |
-| replay                 | -                                                                                     | 重播视频。                                                                                                                                                            |
-| seek                   | time                                                                                  | 跳转到某个时刻进行播放，time 的单位为秒。                                                                                                                             |
-| getCurrentTime         | -                                                                                     | 获取当前的播放时刻，返回的单位为秒。                                                                                                                                  |
-| getDuration            | -                                                                                     | 获取视频总时长，返回的单位为秒，这个需要在视频加载完成以后才可以获取到，可以在 play 事件后获取。                                                                      |
-| getVolume              | -                                                                                     | 获取当前的音量，返回值为 0-1 的实数。ios 和部分 android 会失效。                                                                                                      |
-| setVolume              | -                                                                                     | 设置音量，vol 为 0-1 的实数，ios 和部分 android 会失效。                                                                                                              |
-| loadByUrl              | url，time                                                                             | 直接播放视频 url，time 为可选值（单位秒）。目前只支持同种格式（mp4/flv/m3u8）之间切换。暂不支持直播 rtmp 流切换。                                                     |
-| replayByVidAndPlayAuth | vid：视频 id,playauth：播放凭证                                                       | 目前只支持 H5 播放器。暂不支持不同格式视频间的之间切换。暂不支持直播 rtmp 流切换。                                                                                    |
-| replayByVidAndAuthInfo | 仅 MPS 用户时使用,参数顺序为：vid、accId、accSecret、stsToken、authInfo、domainRegion | 目前只支持 H5 播放器。暂不支持不同格式视频间的之间切换。暂不支持直播 rtmp 流切换。                                                                                    |
-| setPlayerSize          | w，h                                                                                  | 设置播放器大小 w，h 可分别为 400px 像素或 60%百分比。chrome 浏览器下 flash 播放器分别不能小于 397x297。                                                               |
-| setSpeed               | speed                                                                                 | 手动设置播放的倍速，倍速播放仅 H5 支持。移动端可能会失效，比如 android 微信。倍速播放 UI 默认是开启的。如果自定义过 skinLaout 属性，需要添加 speedButton 项到数组里： |
-| >                      | >                                                                                     | {name：“speedButton”，align：“tr”，x：10，y：23}                                                                                                                      |
-| setSanpshotProperties  | width：宽度,height：高度,rate：截图质量                                               | 设置截图参数。                                                                                                                                                        |
-| requestFullScreen      | -                                                                                     | 播放器全屏，仅 H5 支持。                                                                                                                                              |
-| cancelFullScreen       | -                                                                                     | 播放器退出全屏，iOS 调用无效，仅 H5 支持。                                                                                                                            |
-| getIsFullScreen        | -                                                                                     | 获取播放器全屏状态，仅 H5 支持。                                                                                                                                      |
-| getStatus              | -                                                                                     | 获取播放器状态，包含的值：‘init’,‘ready’,‘loading’,‘play’,‘pause’,‘playing’,‘waiting’,‘error’,‘ended’                                                                 |
-| setLiveTimeRange       | 开始时间,结束时间                                                                     | 设置直播的开始结束时间，开启直播时移功能时使用。例子：player.liveShiftSerivce.setLiveTimeRange(“”，‘2018/01/04 20:00:00’)                                             |
-| setRotate              | rotate 旋转角度                                                                       | 参数为旋转角度， 正数为正时针旋转， 负数为逆时针旋转。例如: setRotate(90)。详情参见旋转和镜像。                                                                       |
-| getRotate              | -                                                                                     | 获取旋转角度。详情参见旋转和镜像。                                                                                                                                    |
-| setImage               | image：镜像类型,可选值为：horizon,vertical                                            | 设置镜像，例如: setImage(‘horizon’)。详情参见旋转和镜像。                                                                                                             |
-| dispose                | -                                                                                     | 播放器销毁                                                                                                                                                            |
-| setCover               | cover 封面地址                                                                        | 设置封面                                                                                                                                                              |
-| setProgressMarkers     | markers 打点数据集合                                                                  | 设置打点数据                                                                                                                                                          |
-| setPreviewTime         | time 试看时间                                                                         | 设置试看时间，单位为秒，详情参见试看                                                                                                                                  |
-| getPreviewTime         | -                                                                                     | 获取试看时间                                                                                                                                                          |
-| isPreview              | -                                                                                     | 是否试看                                                                                                                                                              |
-| off                    | ev:事件名[String],handle,事件回调方法[Function]                                       | 通过播放器实例的 off 方法取消绑定的方法                                                                                                                               |
+## 使用示例

-## 4.播放器事件
+### URL 播放

-```html
+```vue
+<VueAliplayerV2
+    source="//player.alicdn.com/video/aliyunmedia.mp4"
+    :options="{
+        autoplay: true,
+        useH5Prism: true,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+### VID + PlayAuth
+
+```vue
+<VueAliplayerV2
+    :options="{
+        vid: '<your-video-id>',
+        playauth: '<your-playauth>',
+        authTimeout: 7200,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+`VID + PlayAuth` 是初始化配置，不需要再传 `source`。如果要在播放器创建后切换，可以调用：
+
+```ts
+playerRef.value?.replayByVidAndPlayAuth(vid, playauth);
+```
+
+### STS
+
+```vue
+<VueAliplayerV2
+    :options="{
+        vid: '<your-video-id>',
+        region: 'cn-shanghai',
+        accessKeyId: '<temporary-access-key-id>',
+        accessKeySecret: '<temporary-access-key-secret>',
+        securityToken: '<temporary-security-token>',
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+### FLV 直播和低延迟
+
+```vue
+<VueAliplayerV2
+    source="//example.com/live.flv"
+    low-latency
+    :options="{
+        isLive: true,
+        autoplay: true,
+        width: '100%',
+        height: '420px'
+    }"
+/>
+```
+
+开启 `low-latency` 后，如果当前播放源格式为 `flv` 且 `options.isLive = true`，组件会默认补充：
+
+```ts
+{
+    enableStashBufferForFlv: false,
+    stashInitialSizeForFlv: 128
+}
+```
+
+如果业务需要其他缓存策略，可以直接在 `options` 中覆盖。
+
+### 直播时移
+
+```ts
+playerRef.value?.setLiveTimeRange('2026/05/23 10:00:00', '2026/05/23 12:00:00');
+```
+
+也可以在初始化时传入官方支持的直播时移配置：
+
+```vue
+<VueAliplayerV2
+    source="//example.com/live.m3u8"
+    :options="{
+        isLive: true,
+        liveStartTime: '2026/05/23 10:00:00',
+        liveOverTime: '2026/05/23 12:00:00'
+    }"
+/>
+```
+
+### 多播放器
+
+```vue
 <template>
-  <vue-aliplayer-v2 @ready="handleReady" />
+    <VueAliplayerV2
+        v-for="item in sources"
+        :key="item"
+        :source="item"
+        :options="options"
+    />
 </template>
-<script>
-  export default {
-    methods: {
-      /**
-       * 播放器事件回调
-       */
-      handleReady(e) {
-        console.log(`ready`, e);
-      },
-    },
-  };
+
+<script setup lang="ts">
+import { reactive } from 'vue';
+
+const sources = [
+    '//player.alicdn.com/video/aliyunmedia.mp4',
+    '//yunqivedio.alicdn.com/user-upload/nXPDX8AASx.mp4'
+];
+
+const options = reactive({
+    autoplay: false,
+    width: '100%',
+    height: '300px'
+});
 </script>
 ```

-可以参考 [播放器事件](https://help.aliyun.com/document_detail/125572.html?spm=a2c4g.11186623.6.1085.36fc6fc57WKZ5P#h2-u64ADu653Eu5668u4E8Bu4EF63)
+v2 会复用相同的 SDK CSS/JS 加载 Promise，多实例挂载时不会重复插入同一份 SDK 标签。

-| 名称              | 说明                                                                                                                                     |
-| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
-| ready             | 播放器视频初始化按钮渲染完毕。播放器 UI 初始设置需要此事件后触发，避免 UI 被初始化所覆盖。播放器提供的方法需要在此事件发生后才可以调用。 |
-| play              | 视频由暂停恢复为播放时触发。                                                                                                             |
-| pause             | 视频暂停时触发。                                                                                                                         |
-| canplay           | 能够开始播放音频/视频时发生，会多次触发，仅 H5 播放器。                                                                                  |
-| playing           | 播放中，会触发多次。                                                                                                                     |
-| ended             | 当前视频播放完毕时触发。                                                                                                                 |
-| liveStreamStop    | 直播流中断时触发。m3u8/flv/rtmp 在重试 5 次未成功后触发。提示上层流中断或需要重新加载视频。PS：m3u8 一直自动重试，不需要上层添加重试。   |
-| onM3u8Retry       | m3u8 直播流中断后重试事件，每次断流只触发一次。                                                                                          |
-| hideBar           | 控制栏自动隐藏事件。                                                                                                                     |
-| showBar           | 控制栏自动显示事件。                                                                                                                     |
-| waiting           | 数据缓冲事件。                                                                                                                           |
-| timeupdate        | 播放位置发生改变时触发，仅 H5 播放器。可通过 getCurrentTime 方法，得到当前播放时间。                                                     |
-| snapshoted        | 截图完成事件。                                                                                                                           |
-| requestFullScreen | 全屏事件，仅 H5 支持。                                                                                                                   |
-| cancelFullScreen  | 取消全屏事件，iOS 下不会触发，仅 H5 支持。                                                                                               |
-| error             | 错误事件。                                                                                                                               |
-| startSeek         | 开始拖拽，参数返回拖拽点的时间。                                                                                                         |
-| completeSeek      | 完成拖拽，参数返回拖拽点的时间。                                                                                                         |
+### 自定义组件和跑马灯

---
+Aliplayer 的自定义组件通常需要额外脚本。可以通过 `componentScripts` 保证扩展脚本在播放器初始化前加载。

-## 5. 图片展示
-
-![图片1](https://github.com/langyuxiansheng/vue-aliplayer-v2/blob/master/images/p1.png)
-![图片2](https://github.com/langyuxiansheng/vue-aliplayer-v2/blob/master/images/p2.png)
-
---
-
-## 6.二次开发 下载项目
-
-```bash
-git clone https://github.com/langyuxiansheng/vue-aliplayer-v2.git
+```vue
+<VueAliplayerV2
+    :source="source"
+    :component-scripts="['/aliplayer-components/marquee.js']"
+    :options="{
+        components: [
+            {
+                name: 'MarqueeComponent',
+                type: window.MarqueeComponent,
+                args: {
+                    text: 'vue-aliplayer-v2'
+                }
+            }
+        ]
+    }"
+/>
 ```

-## Project setup
+播放列表、水印、跑马灯等能力是否可用取决于你加载的 Aliplayer 自定义组件脚本。
+
+### 禁止快进
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    forbid-fast-forward
+/>
+```
+
+该能力通过监听播放进度并回退异常快进行为实现，适合作为轻量业务限制。更强的防绕过需求应结合服务端鉴权、试看、加密播放等方案。
+
+### 失败重试
+
+播放器错误页属于 Aliplayer SDK 内部 UI。业务侧可以监听 `error` 后调用 `retry()` 或 `reload()` 做局部重试。
+
+```ts
+function handleError() {
+    playerRef.value?.retry();
+}
+```
+
+### 可选拦截 track 上报
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    disable-tracking
+    :tracking-url-patterns="['newplayer/track', /\/logstores\//]"
+/>
+```
+
+该能力只拦截已知 URL 规则，属于 wrapper 层兜底方案。生产项目优先使用阿里云官方配置、控制台设置或合规的业务上报策略。
+
+## SSR 和 Nuxt 说明
+
+Aliplayer SDK 依赖浏览器环境中的 `window` 和 DOM。SSR 项目中请只在客户端渲染播放器，例如 Nuxt 中使用 `<ClientOnly>`：
+
+```vue
+<ClientOnly>
+    <VueAliplayerV2 :source="source" />
+</ClientOnly>
+```
+
+## TypeScript
+
+包入口导出以下类型：
+
+```ts
+import type {
+    AliplayerEventName,
+    AliplayerInstance,
+    AliplayerLicense,
+    AliplayerOptions,
+    AliplayerV2Props,
+    VueAliplayerV2Expose,
+    VueAliplayerV2Options
+} from 'vue-aliplayer-v2';
+```
+
+## 版本迁移
+
+### 从 1.x 升级到 2.x
+
+- v2 仅支持 Vue 3，不再考虑 Vue 2 向下兼容。
+- 构建工具迁移为 Vite，库产物输出为 ESM 和 UMD。
+- 全局注册改为 Vue 3 `app.use(VueAliplayerV2, options)`。
+- 组件 ref 建议使用 `ref<VueAliplayerV2Expose | null>`。
+- 默认 SDK 升级为阿里云 `imp-web-player` 2.37.0 路径。
+- 新增 `license`、`lowLatency`、`normalizeSourceUrl`、`componentScripts`、`disableTracking` 等配置。
+- 旧项目如需继续使用 Vue 2 版本，请固定安装 `vue-aliplayer-v2@1.x`。
+
+## 常见问题
+
+### 播放器没有显示
+
+先确认页面只在浏览器端渲染，并检查 `sdk-error` 事件。常见原因包括 SDK 地址被拦截、License 未配置、播放源跨域、容器高度为 0。
+
+### 新版 SDK 提示 License 问题
+
+请到阿里云控制台申请 Web 播放器 License，并通过 `license` prop 或 `options.license` 传入：
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    :license="{ domain: 'example.com', key: 'your-license-key' }"
+/>
+```
+
+### URL 中有中文或空格播放失败
+
+默认 `normalizeSourceUrl = true` 会对播放源执行 `encodeURI`。如果你的业务已经完成 URL 编码，可以显式关闭：
+
+```vue
+<VueAliplayerV2
+    :source="source"
+    :normalize-source-url="false"
+/>
+```
+
+### 切换播放源时应该用 `source` 还是 `loadByUrl`
+
+普通 Vue 场景优先更新 `source`。组件会自动判断同格式和跨格式切换。命令式场景可以调用 `playerRef.value?.loadByUrl(url)`。
+
+## 本地开发

 ```bash
-cd vue-aliplayer-v2
-
 npm install
-```
-
-### Compiles and hot-reloads for development
-
-```bash
 npm run dev
 ```

-### Compiles and minifies for production
+类型检查：
+
+```bash
+npm run type-check
+```
+
+构建 demo：

 ```bash
 npm run build
 ```

-### Lints and fixes files
+构建组件库：

 ```bash
-npm run lint
+npm run lib
 ```

-## 7.缺陷 & 后期计划
+## License

-> 2019 年 12 月 27 日 更新优化局部引用方式
-
-> 您有功能建议,或者 bug 反馈请留言.
-
-## 8.感谢
-
---
-
- vue-aliplayer 的作者,项目地址:https://github.com/slacrey/vue-aliplayer
-
- Alipayer 阿里云的开源播放器 https://help.aliyun.com/document_detail/125572.html?spm=a2c4g.11186623.6.1085.36fc6fc57WKZ5P#h2-u64ADu653Eu5668u4E8Bu4EF63
-
-### Customize configuration
-
-See [Configuration Reference](https://cli.vuejs.org/config/).
-
-## 更新日志
-
-> v1.3.0 修复部分已知bug,增加forbidFastForward 属性,感谢 "william-xue"网友的功能提交.
-
- sdk 版本更新,默认 SDK 版本由 2.9.3 更新为 2.9.20
- 默认注释更新
- 增加禁止用户拖拽快进的属性选项 forbidFastForward [Boolean] 默认 false
-
-> v1.2.9 修正部分默认属性, 感谢"Schean17"网友的反馈与建议.
-
-> v1.2.8 更换底层默认 sdk 版本为 2.9.3 修复 options 遇到 update loop 错误 感谢"litmonw"网友的反馈与建议.
-
-> v1.2.7 更换底层默认 sdk 版本为 2.9.1 的版本. 更新线上演示 demo 的选项
-
-> v1.2.6 优化 beforeDestroy() 部分的代码.
-
-> v1.2.5 更换默认的播放器 SDK 版本 2.8.2 => 2.9.0,2.8.2 的版本存在多个播放器同时播放直播流异常的 bug,增加了全局 SDK 版本配置,可以在 Vue.use()的时候进行配置.
-
-> v1.2.4 修复多个播放器加载,只初始化一个播放器的 bug.文档部分更新,增加了问题栏. 感谢"沙洲 ad"的反馈与建议.
-
-> v1.2.3 优化播放器的初始化代码,调整包内结构,优化局部组件的注册方式,也兼容老版本的引用方式.文档部分更新,增加了问题栏. 感谢"liangzhiyuan2015"和"fancheur"两位网友的反馈与建议.
-
-> v1.2.2 修复指定 id 情况下,播放器报错"没有为播放器指定容器",目前移除外部指定 id 的方式,所有的播放器 id 都由内部生成,不再由外部指定容器(外部指定的意义并不大),其它的说明:更新 1.2.1 后报错 Uncaught TypeError: 没有为播放器指定容器,因为源码中变更了部分代码,以及最大限度的简化代码,组件内部的根容器就只有一个 div 容器,导致以前外部指定 id 的时候,容器 id 与外部的不一致,导致抛出异常了,现在已经紧急修复了,若在使用,请更新到 v1.2.2 的版本;如果使用了外部指定 id 的方式请移除外部的 id.否则 id 会出现重复的情况., 感谢"liyoro"的反馈和建议.
-
-> v1.2.1 修复直播播放的情况下,播放器已经销毁,而后台还在继续下载资源造成卡顿的 bug,修复多个播放器只渲染 1 个的 bug, 感谢"Jonauil"和"guangming95"两位网友的反馈和建议.
-
-> v1.2.0 修复播放源(MP4/m3u8)之间切换无法正常播放的 bug,增加 options 配置项动态响应功能,优化部分播放器的逻辑, 感谢"liyoro"网友的反馈和建议.
-
-> v1.1.9 修复播放源(修复 prop:source 类型验证报错), 感谢"hugo2017"和“nullF”网友的反馈.
-
-> v1.1.8 修复播放源(增加 source 属性类型错误),修复获取播放器状态 getStatus()方法报错, 感谢"kongjigu"网友的反馈.
-
-> v1.1.7 增加动态切换播放源(增加 source 属性)功能 感谢"wikimo"和"jieruian"两位网友的反馈建议.
-
-> v1.1.6 修复部分已知 bug 和优化局部的引用方式
-
---
-
-## 其它问题
-
-1. IOS 或者其它设备无法全屏播放,或者点击全屏按钮的时候也只是显示竖屏？
-
-> 方案与问题所在:
-
-一般情况下可能是开启了强制竖屏(也就是屏幕锁定)打开后就会竖屏而不会全屏了！如下关闭就可以了：
-参考 issues: https://github.com/langyuxiansheng/vue-aliplayer-v2/issues/25
-
-开启了屏幕锁定，只要上拉控制中心，点击屏幕锁定关闭就可以了！
-
-也可能是播放器或者浏览器兼容性问题.
+[MIT](./LICENSE)
--- a/babel.config.js
+++ b/babel.config.js
@ -1,5 +0,0 @@
-module.exports = {
-  presets: [
-    '@vue/app'
-  ]
-}
--- a/dist/assets/index-D3stZ_L4.css
+++ b/dist/assets/index-D3stZ_L4.css
--- a/dist/assets/index-DqwC15gS.js
+++ b/dist/assets/index-DqwC15gS.js
--- a/dist/css/index.06951331.css
+++ b/dist/css/index.06951331.css
@ -1 +0,0 @@
-[data-v-9b14a31e]{margin:0;padding:0}.remove-text[data-v-9b14a31e]{text-align:center;padding:20px;font-size:24px}.player-btns[data-v-9b14a31e]{width:100%;display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-pack:justify;-ms-flex-pack:justify;justify-content:space-between;-ms-flex-wrap:wrap;flex-wrap:wrap}.player-btns span[data-v-9b14a31e]{margin:0 auto;display:inline-block;padding:5px 10px;width:150px;height:40px;line-height:40px;border:1px solid #eee;background:#e1e1e1;border-radius:10px;text-align:center;margin:20px auto;cursor:pointer}
--- a/dist/index.html
+++ b/dist/index.html
@ -1 +1,14 @@
-<!DOCTYPE html><html lang=en><head><meta charset=utf-8><meta http-equiv=X-UA-Compatible content="IE=edge"><meta name=viewport content="width=device-width,initial-scale=1"><link rel=icon href=/vue-aliplayer-v2/favicon.ico><title>vue-aliplayer-v2</title><link href=/vue-aliplayer-v2/css/index.06951331.css rel=preload as=style><link href=/vue-aliplayer-v2/js/chunk-vendors.69bad5f4.js rel=preload as=script><link href=/vue-aliplayer-v2/js/index.b7f22f1a.js rel=preload as=script><link href=/vue-aliplayer-v2/css/index.06951331.css rel=stylesheet></head><body><noscript><strong>We're sorry but vue-aliplayer-v2 doesn't work properly without JavaScript enabled. Please enable it to continue.</strong></noscript><div id=app></div><script src=/vue-aliplayer-v2/js/chunk-vendors.69bad5f4.js></script><script src=/vue-aliplayer-v2/js/index.b7f22f1a.js></script></body></html>
+<!doctype html>
+<html lang="zh-CN">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <link rel="icon" href="/vue-aliplayer-v2/favicon.ico">
+        <title>vue-aliplayer-v2</title>
+      <script type="module" crossorigin src="/vue-aliplayer-v2/assets/index-DqwC15gS.js"></script>
+      <link rel="stylesheet" crossorigin href="/vue-aliplayer-v2/assets/index-D3stZ_L4.css">
+    </head>
+    <body>
+        <div id="app"></div>
+    </body>
+</html>
--- a/dist/js/chunk-vendors.69bad5f4.js
+++ b/dist/js/chunk-vendors.69bad5f4.js
--- a/dist/js/index.b7f22f1a.js
+++ b/dist/js/index.b7f22f1a.js
--- a/env.d.ts
+++ b/env.d.ts
@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+    import type { DefineComponent } from 'vue';
+
+    const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>;
+    export default component;
+}
--- a/examples/App.vue
+++ b/examples/App.vue
--- a/examples/main.js
+++ b/examples/main.js
@ -1,11 +0,0 @@
-import Vue from 'vue';
-import App from './App.vue';
-import VueAliplayerV2 from '../packages';
-Vue.use(VueAliplayerV2,{
-    // cssLink: 'https://g.alicdn.com/de/prismplayer/2.8.2/skins/default/aliplayer-min.css',
-    // scriptSrc: 'https://g.alicdn.com/de/prismplayer/2.8.2/aliplayer-min.js'
-});
-Vue.config.productionTip = false;
-new Vue({
-    render: h => h(App),
-}).$mount('#app');
--- a/examples/main.ts
+++ b/examples/main.ts
@ -0,0 +1,9 @@
+import { createApp } from 'vue';
+import App from './App.vue';
+
+/**
+ * 启动 demo 应用。
+ *
+ * demo 直接引用源码入口，便于本地调试组件行为和 GitHub Pages 构建保持一致。
+ */
+createApp(App).mount('#app');
--- a/index.html
+++ b/index.html
@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <link rel="icon" href="/favicon.ico">
+        <title>vue-aliplayer-v2</title>
+    </head>
+    <body>
+        <div id="app"></div>
+        <script type="module" src="/examples/main.ts"></script>
+    </body>
+</html>
--- a/lib/demo.html
+++ b/lib/demo.html
@ -1,10 +0,0 @@
-<meta charset="utf-8">
-<title>vue-aliplayer-v2 demo</title>
-<script src="./vue-aliplayer-v2.umd.js"></script>
-
-<link rel="stylesheet" href="./vue-aliplayer-v2.css">
-
-
-<script>
-console.log(vue-aliplayer-v2)
-</script>
--- a/lib/types/AliplayerV2/index.vue.d.ts
+++ b/lib/types/AliplayerV2/index.vue.d.ts
@ -0,0 +1,59 @@
+import type { AliplayerOptions, AliplayerV2Props, VueAliplayerV2Expose } from './types';
+declare const __VLS_export: import("vue").DefineComponent<AliplayerV2Props, VueAliplayerV2Expose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    canplay: (payload?: unknown) => any;
+    ended: (payload?: unknown) => any;
+    error: (payload?: unknown) => any;
+    pause: (payload?: unknown) => any;
+    play: (payload?: unknown) => any;
+    playing: (payload?: unknown) => any;
+    timeupdate: (payload?: unknown) => any;
+    waiting: (payload?: unknown) => any;
+    ready: (payload?: unknown) => any;
+    liveStreamStop: (payload?: unknown) => any;
+    onM3u8Retry: (payload?: unknown) => any;
+    hideBar: (payload?: unknown) => any;
+    showBar: (payload?: unknown) => any;
+    snapshoted: (payload?: unknown) => any;
+    requestFullScreen: (payload?: unknown) => any;
+    cancelFullScreen: (payload?: unknown) => any;
+    startSeek: (payload?: unknown) => any;
+    completeSeek: (payload?: unknown) => any;
+    "sdk-error": (error: Error) => any;
+}, string, import("vue").PublicProps, Readonly<AliplayerV2Props> & Readonly<{
+    onCanplay?: ((payload?: unknown) => any) | undefined;
+    onEnded?: ((payload?: unknown) => any) | undefined;
+    onError?: ((payload?: unknown) => any) | undefined;
+    onPause?: ((payload?: unknown) => any) | undefined;
+    onPlay?: ((payload?: unknown) => any) | undefined;
+    onPlaying?: ((payload?: unknown) => any) | undefined;
+    onTimeupdate?: ((payload?: unknown) => any) | undefined;
+    onWaiting?: ((payload?: unknown) => any) | undefined;
+    onReady?: ((payload?: unknown) => any) | undefined;
+    onLiveStreamStop?: ((payload?: unknown) => any) | undefined;
+    onOnM3u8Retry?: ((payload?: unknown) => any) | undefined;
+    onHideBar?: ((payload?: unknown) => any) | undefined;
+    onShowBar?: ((payload?: unknown) => any) | undefined;
+    onSnapshoted?: ((payload?: unknown) => any) | undefined;
+    onRequestFullScreen?: ((payload?: unknown) => any) | undefined;
+    onCancelFullScreen?: ((payload?: unknown) => any) | undefined;
+    onStartSeek?: ((payload?: unknown) => any) | undefined;
+    onCompleteSeek?: ((payload?: unknown) => any) | undefined;
+    "onSdk-error"?: ((error: Error) => any) | undefined;
+}>, {
+    source: string | null;
+    autoFormat: boolean;
+    forbidFastForward: boolean;
+    license: import("./types").AliplayerLicense | null;
+    lowLatency: boolean;
+    normalizeSourceUrl: boolean;
+    options: AliplayerOptions | null;
+    sdkVersion: string;
+    cssLink: string;
+    scriptSrc: string;
+    componentScripts: string[];
+    disableTracking: boolean;
+    trackingUrlPatterns: Array<string | RegExp>;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;
+//# sourceMappingURL=index.vue.d.ts.map
--- a/lib/types/AliplayerV2/sdkLoader.d.ts
+++ b/lib/types/AliplayerV2/sdkLoader.d.ts
@ -0,0 +1,51 @@
+/**
+ * 默认阿里云 Web 播放器 SDK 版本。
+ *
+ * 该版本来自阿里云播放器 SDK 下载页。后续升级默认 SDK 时，只需要同步修改该常量。
+ */
+export declare const DEFAULT_SDK_VERSION = "2.37.0";
+/**
+ * 默认 Aliplayer CSS 地址。
+ *
+ * 2.16.3 之后阿里云官方资源路径从 `de/prismplayer` 切换到了
+ * `apsara-media-box/imp-web-player`，因此这里使用新路径。
+ */
+export declare const DEFAULT_CSS_LINK = "https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/skins/default/aliplayer-min.css";
+/**
+ * 默认 Aliplayer JS 地址。
+ */
+export declare const DEFAULT_SCRIPT_SRC = "https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/aliplayer-min.js";
+/**
+ * 根据 SDK 版本生成官方 CSS 地址。
+ *
+ * @param version 阿里云 Web 播放器 SDK 版本号。
+ * @returns 官方 `imp-web-player` CSS 资源地址。
+ */
+export declare function getCssLinkByVersion(version: string): string;
+/**
+ * 根据 SDK 版本生成官方 JS 地址。
+ *
+ * @param version 阿里云 Web 播放器 SDK 版本号。
+ * @returns 官方 `imp-web-player` JS 资源地址。
+ */
+export declare function getScriptSrcByVersion(version: string): string;
+/**
+ * 加载 Aliplayer SDK 的 CSS 和 JS。
+ *
+ * 该方法会先插入 CSS，再等待 JS 加载完成。它会复用已有标签和加载 Promise，
+ * 因而可以安全地被多个播放器实例同时调用。
+ *
+ * @param cssLink Aliplayer 样式地址。
+ * @param scriptSrc Aliplayer 脚本地址。
+ */
+export declare function loadAliplayerSdk(cssLink: string, scriptSrc: string): Promise<void>;
+/**
+ * 按顺序加载额外扩展脚本。
+ *
+ * 主要用于 Aliplayer 自定义组件，例如播放列表、跑马灯、水印等。顺序加载能保证
+ * 后一个脚本可以依赖前一个脚本暴露的全局对象。
+ *
+ * @param scriptUrls 需要在播放器初始化前加载的脚本地址列表。
+ */
+export declare function loadExtraScripts(scriptUrls?: string[]): Promise<void>;
+//# sourceMappingURL=sdkLoader.d.ts.map
--- a/lib/types/AliplayerV2/source.d.ts
+++ b/lib/types/AliplayerV2/source.d.ts
@ -0,0 +1,27 @@
+/**
+ * 组件可以从播放地址中推断出的媒体格式。
+ *
+ * `null` 表示无法可靠判断格式，组件会把格式判断交给 Aliplayer SDK。
+ */
+export type SourceFormat = 'mp4' | 'm3u8' | 'flv' | 'rtmp' | 'mp3' | null;
+/**
+ * 从播放地址推断媒体格式。
+ *
+ * 推断逻辑会忽略 query 和 hash，仅根据协议或路径后缀判断。RTMP 地址优先根据协议识别，
+ * 其他格式根据后缀识别。
+ *
+ * @param source 播放源地址。
+ * @returns 推断出的媒体格式；无法判断时返回 `null`。
+ */
+export declare function inferSourceFormat(source?: string | null): SourceFormat;
+/**
+ * 标准化播放源 URL。
+ *
+ * 目前只做 `encodeURI`，用于处理中文文件名、空格等常见未编码地址。`data:` 和 `blob:`
+ * 地址不应该被编码，因此会原样返回。若浏览器环境对某些非法 URL 抛错，也会回退到原始地址。
+ *
+ * @param source 播放源地址。
+ * @returns 标准化后的地址；空值保持为空。
+ */
+export declare function normalizeSource(source?: string | null): string | null;
+//# sourceMappingURL=source.d.ts.map
--- a/lib/types/AliplayerV2/tracking.d.ts
+++ b/lib/types/AliplayerV2/tracking.d.ts
@ -0,0 +1,21 @@
+/**
+ * 安装 Aliplayer 统计请求拦截器。
+ *
+ * 该方法会拦截命中规则的 `fetch` 和 `XMLHttpRequest` 请求，避免向已知统计地址发送数据。
+ * 这是 wrapper 层提供的可选缓解方案，不替代阿里云官方 SDK 的开关能力。由于它会修改全局
+ * 网络 API，只有在用户显式设置 `disableTracking` 时才会调用。
+ *
+ * @param patterns 需要拦截的 URL 片段或正则。不传时使用默认已知统计地址。
+ */
+export declare function installTrackingBlocker(patterns?: Array<string | RegExp>): void;
+declare global {
+    interface XMLHttpRequest {
+        /**
+         * 当前 XHR 是否命中 vue-aliplayer-v2 的统计拦截规则。
+         *
+         * 这是内部标记字段，仅用于 `open` 和 `send` 两个 patch 方法之间传递状态。
+         */
+        __vueAliplayerV2Blocked?: boolean;
+    }
+}
+//# sourceMappingURL=tracking.d.ts.map
--- a/lib/types/AliplayerV2/types.d.ts
+++ b/lib/types/AliplayerV2/types.d.ts
@ -0,0 +1,525 @@
+import type { Plugin } from 'vue';
+/**
+ * 全局插件安装配置。
+ *
+ * 这些配置会作为组件 props 的默认值使用，适合在 `app.use(VueAliplayerV2, options)` 时
+ * 统一声明 SDK 版本、资源地址和公共扩展行为。单个组件仍然可以通过同名 props 覆盖这些默认值。
+ */
+export interface VueAliplayerV2Options {
+    /**
+     * 阿里云 Web 播放器 SDK 版本号。
+     *
+     * 当 `cssLink` 或 `scriptSrc` 未显式传入时，组件会根据该版本号生成官方
+     * `apsara-media-box/imp-web-player` 资源地址。
+     */
+    sdkVersion?: string;
+    /**
+     * Aliplayer CSS 资源地址。
+     *
+     * 显式传入后优先级高于 `sdkVersion` 自动生成的地址。
+     */
+    cssLink?: string;
+    /**
+     * Aliplayer JS 资源地址。
+     *
+     * 显式传入后优先级高于 `sdkVersion` 自动生成的地址。
+     */
+    scriptSrc?: string;
+    /**
+     * 自定义组件或业务扩展脚本地址列表。
+     *
+     * 组件会在创建播放器实例前按顺序加载这些脚本，适合接入播放列表、跑马灯、
+     * 自定义水印等 Aliplayer 自定义组件。
+     */
+    componentScripts?: string[];
+    /**
+     * 是否启用已知 Aliplayer 统计上报拦截。
+     *
+     * 该能力是 wrapper 层的可选兜底方案，优先建议使用阿里云官方配置项。
+     */
+    disableTracking?: boolean;
+    /**
+     * 需要拦截的统计上报 URL 片段或正则。
+     *
+     * 默认只拦截已知的 `newplayer/track` 地址；传入该字段可扩展业务侧发现的其他上报地址。
+     */
+    trackingUrlPatterns?: Array<string | RegExp>;
+}
+/**
+ * `<VueAliplayerV2 />` 组件 props。
+ *
+ * 除了播放器业务配置外，还继承了全局插件配置，使每个组件实例都可以单独覆盖 SDK
+ * 版本、资源地址、扩展脚本和统计拦截策略。
+ */
+export interface AliplayerV2Props extends VueAliplayerV2Options {
+    /**
+     * 是否根据 `source` 后缀自动推断 `format`。
+     *
+     * 支持 `mp4`、`m3u8`、`flv`、`mp3`、`rtmp`。当 `options.format` 已设置时，
+     * 组件不会覆盖用户显式传入的格式。
+     */
+    autoFormat?: boolean;
+    /**
+     * 是否禁止用户拖拽快进。
+     *
+     * 开启后组件会监听 `timeupdate`，当检测到播放位置向前跳跃超过阈值时回退到上一次位置。
+     */
+    forbidFastForward?: boolean;
+    /**
+     * Aliplayer License 配置。
+     *
+     * 新版阿里云 Web 播放器要求业务域名绑定 License。该字段会合并到最终的
+     * Aliplayer 初始化 options 中，优先级高于全局配置，等价于 `options.license`。
+     */
+    license?: AliplayerLicense | null;
+    /**
+     * 是否启用 FLV 直播低延迟预设。
+     *
+     * 当 `options.isLive` 为 `true` 且推断格式为 `flv` 时，组件会默认关闭 FLV stash buffer
+     * 并设置较小的初始缓存。用户仍可在 `options` 中显式覆盖这些字段。
+     */
+    lowLatency?: boolean;
+    /**
+     * 是否对播放源 URL 执行 `encodeURI`。
+     *
+     * 用于处理中文文件名、空格等未编码 URL。`data:` 和 `blob:` 地址会被原样保留。
+     */
+    normalizeSourceUrl?: boolean;
+    /**
+     * 透传给 Aliplayer 的原始初始化配置。
+     *
+     * 组件只会补充必要的 `id`、`source`、`license`、`format` 和低延迟默认值，
+     * 其他字段全部保持透传。
+     */
+    options?: AliplayerOptions | null;
+    /**
+     * 播放源 URL。
+     *
+     * 存在时优先于 `options.source`。同格式切换时优先调用 `loadByUrl`，跨格式切换时会重建播放器。
+     */
+    source?: string | null;
+}
+/**
+ * 阿里云 Web 播放器 License 信息。
+ */
+export interface AliplayerLicense {
+    /**
+     * 申请 License 时绑定的网站域名。
+     */
+    domain: string;
+    /**
+     * 阿里云控制台生成的 License Key。
+     */
+    key: string;
+}
+/**
+ * 当前组件会透传的 Aliplayer 事件名。
+ */
+export type AliplayerEventName = 'ready' | 'play' | 'pause' | 'canplay' | 'playing' | 'ended' | 'liveStreamStop' | 'onM3u8Retry' | 'hideBar' | 'showBar' | 'waiting' | 'timeupdate' | 'snapshoted' | 'requestFullScreen' | 'cancelFullScreen' | 'error' | 'startSeek' | 'completeSeek';
+/**
+ * Aliplayer 初始化配置。
+ *
+ * 这里只声明 wrapper 中常用和文档中重点暴露的字段。阿里云 SDK 的配置项较多，
+ * 因此保留索引签名以允许业务侧继续传入官方新增或未显式列出的参数。
+ */
+export interface AliplayerOptions {
+    /**
+     * 播放器容器 DOM id。组件内部会自动生成并覆盖该字段。
+     */
+    id?: string;
+    /**
+     * 播放源 URL。
+     */
+    source?: string;
+    /**
+     * 播放器宽度，例如 `100%` 或 `640px`。
+     */
+    width?: string;
+    /**
+     * 是否自动播放。
+     */
+    autoplay?: boolean;
+    /**
+     * 是否为直播流。
+     */
+    isLive?: boolean;
+    /**
+     * 播放源格式，例如 `mp4`、`m3u8`、`flv`。
+     */
+    format?: string;
+    /**
+     * Aliplayer License 配置。
+     */
+    license?: AliplayerLicense;
+    /**
+     * 点播视频 ID，用于 VID + PlayAuth 或 STS 播放。
+     */
+    vid?: string;
+    /**
+     * 点播播放凭证。
+     */
+    playauth?: string;
+    /**
+     * STS 临时 AccessKey ID。
+     */
+    accessKeyId?: string;
+    /**
+     * STS 安全令牌。
+     */
+    securityToken?: string;
+    /**
+     * STS 临时 AccessKey Secret。
+     */
+    accessKeySecret?: string;
+    /**
+     * 媒资所在地域，例如 `cn-shanghai`。
+     */
+    region?: string;
+    /**
+     * 播放地址有效时长，单位秒。
+     */
+    authTimeout?: number;
+    /**
+     * Aliplayer 自定义组件配置。
+     */
+    components?: unknown[];
+    /**
+     * FLV 直播是否启用 stash buffer。
+     */
+    enableStashBufferForFlv?: boolean;
+    /**
+     * FLV 初始缓存大小。
+     */
+    stashInitialSizeForFlv?: number;
+    /**
+     * RTS SDK 版本号。
+     */
+    rtsVersion?: string;
+    /**
+     * 允许传入阿里云播放器官方新增字段或业务侧自定义字段。
+     */
+    [key: string]: unknown;
+}
+/**
+ * Aliplayer 全屏服务对象。
+ */
+export interface AliplayerFullscreenService {
+    /**
+     * 进入全屏。
+     */
+    requestFullScreen: () => void;
+    /**
+     * 退出全屏。
+     */
+    cancelFullScreen: () => void;
+    /**
+     * 获取当前是否处于全屏状态。
+     */
+    getIsFullScreen: () => boolean;
+}
+/**
+ * Aliplayer 直播时移服务对象。
+ */
+export interface AliplayerLiveShiftService {
+    /**
+     * 设置直播时移的可播放时间范围。
+     *
+     * @param beginTime 起始时间，通常为 `YYYY/MM/DD HH:mm:ss`。
+     * @param endTime 结束时间，通常为 `YYYY/MM/DD HH:mm:ss`。
+     */
+    setLiveTimeRange: (beginTime: string, endTime: string) => void;
+}
+/**
+ * Aliplayer 播放器实例。
+ *
+ * 该接口描述组件会调用或暴露的底层 SDK 方法，并非阿里云播放器完整类型定义。
+ */
+export interface AliplayerInstance {
+    /**
+     * 监听底层播放器事件。
+     *
+     * @param eventName 事件名。
+     * @param handler 事件回调。
+     */
+    on: (eventName: string, handler: (event?: unknown) => void) => void;
+    /**
+     * 取消监听底层播放器事件。
+     *
+     * 部分 SDK 版本可能没有该方法，因此这里声明为可选。
+     */
+    off?: (eventName: string, handler: (event?: unknown) => void) => void;
+    /**
+     * 播放视频。
+     */
+    play: () => void;
+    /**
+     * 暂停视频。
+     */
+    pause: () => void;
+    /**
+     * 从头重播视频。
+     */
+    replay: () => void;
+    /**
+     * 跳转到指定播放时间。
+     *
+     * @param time 秒数。
+     */
+    seek: (time: number) => void;
+    /**
+     * 获取当前播放时间，单位秒。
+     */
+    getCurrentTime: () => number;
+    /**
+     * 获取视频总时长，单位秒。
+     */
+    getDuration: () => number;
+    /**
+     * 获取当前音量，范围通常为 0 到 1。
+     */
+    getVolume: () => number;
+    /**
+     * 设置音量。
+     *
+     * @param volume 音量，范围通常为 0 到 1。
+     */
+    setVolume: (volume: number) => void;
+    /**
+     * 通过 URL 切换播放源。
+     *
+     * @param url 新播放地址。
+     * @param time 可选起播时间，单位秒。
+     */
+    loadByUrl: (url: string, time?: number) => void;
+    /**
+     * 使用 VID + PlayAuth 重新播放。
+     */
+    replayByVidAndPlayAuth: (vid: string, playauth: string) => void;
+    /**
+     * 使用 MPS 鉴权信息重新播放。
+     */
+    replayByVidAndAuthInfo: (vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void;
+    /**
+     * 设置播放器尺寸。
+     */
+    setPlayerSize: (width: string, height: string) => void;
+    /**
+     * 设置倍速。
+     */
+    setSpeed: (speed: number) => void;
+    /**
+     * 设置截图参数。
+     */
+    setSanpshotProperties: (width: number, height: number, rate: number) => void;
+    /**
+     * 全屏服务。
+     */
+    fullscreenService?: AliplayerFullscreenService;
+    /**
+     * 获取播放器状态。
+     */
+    getStatus: () => string;
+    /**
+     * 直播时移服务。字段名保留阿里云 SDK 原始拼写。
+     */
+    liveShiftSerivce?: AliplayerLiveShiftService;
+    /**
+     * 设置视频旋转角度。
+     */
+    setRotate: (rotate: number) => void;
+    /**
+     * 获取当前视频旋转角度。
+     */
+    getRotate: () => number;
+    /**
+     * 设置视频镜像。
+     */
+    setImage: (image: string) => void;
+    /**
+     * 销毁播放器实例并释放底层资源。
+     */
+    dispose: () => void;
+    /**
+     * 设置封面图。
+     */
+    setCover: (cover: string) => void;
+    /**
+     * 设置进度条打点。
+     */
+    setProgressMarkers: (markers: unknown[]) => void;
+    /**
+     * 设置试看时间。
+     */
+    setPreviewTime: (time: number) => void;
+    /**
+     * 获取试看时间。
+     */
+    getPreviewTime: () => number;
+    /**
+     * 判断当前是否处于试看状态。
+     */
+    isPreview: () => boolean;
+}
+/**
+ * 通过 Vue `ref` 暴露给业务代码调用的组件方法。
+ *
+ * 方法名基本保持 1.x 版本和阿里云 SDK 的命名，便于迁移旧项目和查阅官方文档。
+ */
+export interface VueAliplayerV2Expose {
+    /**
+     * 获取底层 Aliplayer 实例。
+     */
+    getPlayer: () => AliplayerInstance | null;
+    /**
+     * 加载 SDK 并初始化播放器。
+     */
+    init: () => Promise<void>;
+    /**
+     * 使用当前 props/options 立即创建播放器实例。
+     */
+    initPlayer: () => void;
+    /**
+     * 局部重载播放器。
+     *
+     * @param nextSource 可选的新播放地址。同格式地址会优先走底层 `loadByUrl`。
+     */
+    reload: (nextSource?: string) => Promise<void>;
+    /**
+     * 播放失败后的业务重试入口。
+     *
+     * 当前实现与 `reload` 等价，命名上更适合在 `error` 回调中使用。
+     */
+    retry: (nextSource?: string) => Promise<void>;
+    /**
+     * 播放视频。
+     */
+    play: () => void;
+    /**
+     * 暂停视频。
+     */
+    pause: () => void;
+    /**
+     * 从头重播视频。
+     */
+    replay: () => void;
+    /**
+     * 跳转到指定播放时间。
+     */
+    seek: (time: number) => void;
+    /**
+     * 获取当前播放时间。
+     */
+    getCurrentTime: () => number | undefined;
+    /**
+     * 获取视频总时长。
+     */
+    getDuration: () => number | undefined;
+    /**
+     * 获取当前音量。
+     */
+    getVolume: () => number | undefined;
+    /**
+     * 设置当前音量。
+     */
+    setVolume: (volume: number) => void;
+    /**
+     * 通过 URL 切换播放源。
+     */
+    loadByUrl: (url: string, time?: number) => void;
+    /**
+     * 使用 VID + PlayAuth 重新播放。
+     */
+    replayByVidAndPlayAuth: (vid: string, playauth: string) => void;
+    /**
+     * 使用 MPS 鉴权信息重新播放。
+     */
+    replayByVidAndAuthInfo: (vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void;
+    /**
+     * 设置播放器尺寸。
+     */
+    setPlayerSize: (width: string, height: string) => void;
+    /**
+     * 设置倍速。
+     */
+    setSpeed: (speed: number) => void;
+    /**
+     * 设置截图参数。
+     */
+    setSanpshotProperties: (width: number, height: number, rate: number) => void;
+    /**
+     * 进入全屏。
+     */
+    requestFullScreen: () => void;
+    /**
+     * 退出全屏。
+     */
+    cancelFullScreen: () => void;
+    /**
+     * 获取是否处于全屏状态。
+     */
+    getIsFullScreen: () => boolean | undefined;
+    /**
+     * 获取播放器状态。
+     */
+    getStatus: () => string | undefined;
+    /**
+     * 设置直播时移可播放范围。
+     */
+    setLiveTimeRange: (beginTime: string, endTime: string) => void;
+    /**
+     * 设置视频旋转角度。
+     */
+    setRotate: (rotate: number) => void;
+    /**
+     * 获取视频旋转角度。
+     */
+    getRotate: () => number | undefined;
+    /**
+     * 设置视频镜像。
+     */
+    setImage: (image: string) => void;
+    /**
+     * 销毁播放器实例。
+     */
+    dispose: () => void;
+    /**
+     * 设置封面图。
+     */
+    setCover: (cover: string) => void;
+    /**
+     * 设置进度条打点。
+     */
+    setProgressMarkers: (markers: unknown[]) => void;
+    /**
+     * 设置试看时间。
+     */
+    setPreviewTime: (time: number) => void;
+    /**
+     * 获取试看时间。
+     */
+    getPreviewTime: () => number | undefined;
+    /**
+     * 判断当前是否处于试看状态。
+     */
+    isPreview: () => boolean | undefined;
+    /**
+     * 取消监听底层播放器事件。
+     */
+    off: (eventName: string, handler: (event?: unknown) => void) => void;
+}
+/**
+ * 兼容 Vue 插件安装语义的组件类型。
+ */
+export type VueAliplayerV2Plugin = Plugin & {
+    /**
+     * 兼容 1.x 局部注册写法的组件别名。
+     */
+    Player?: unknown;
+};
+declare global {
+    interface Window {
+        Aliplayer?: (options: AliplayerOptions) => AliplayerInstance;
+        [key: string]: unknown;
+    }
+}
+//# sourceMappingURL=types.d.ts.map
--- a/lib/types/index.d.ts
+++ b/lib/types/index.d.ts
@ -0,0 +1,57 @@
+import type { App } from 'vue';
+import VueAliplayerV2 from './AliplayerV2/index.vue';
+import type { VueAliplayerV2Options } from './AliplayerV2/types';
+/**
+ * 对外重新导出组件相关类型。
+ *
+ * 使用方可以直接从包入口导入类型，不需要关心内部目录结构。
+ */
+export type { AliplayerEventName, AliplayerInstance, AliplayerLicense, AliplayerOptions, AliplayerV2Props, VueAliplayerV2Expose, VueAliplayerV2Options } from './AliplayerV2/types';
+/**
+ * 带 Vue 插件安装能力的组件类型。
+ *
+ * Vue SFC 默认导出的类型不包含运行时追加的 `install`、`Player` 和 props 默认值修改能力，
+ * 因此在入口处扩展该类型，保证后续赋值过程在 TypeScript 下可描述。
+ */
+type InstallableVueAliplayerV2 = typeof VueAliplayerV2 & {
+    /**
+     * Vue 插件安装方法，支持 `app.use(VueAliplayerV2, options)`。
+     */
+    install: (app: App, options?: VueAliplayerV2Options) => void;
+    /**
+     * 兼容旧版本 `VueAliplayerV2.Player` 的局部注册写法。
+     */
+    Player: typeof VueAliplayerV2;
+    /**
+     * 组件 props 运行时定义。
+     *
+     * 这里仅列出入口需要改写默认值的 props。
+     */
+    props: {
+        sdkVersion: {
+            default: string | (() => string);
+        };
+        cssLink: {
+            default: string | (() => string);
+        };
+        scriptSrc: {
+            default: string | (() => string);
+        };
+        componentScripts: {
+            default: string[] | (() => string[]);
+        };
+        disableTracking: {
+            default: boolean | (() => boolean);
+        };
+        trackingUrlPatterns: {
+            default: Array<string | RegExp> | (() => Array<string | RegExp>);
+        };
+    };
+};
+/**
+ * 添加插件安装能力后的播放器组件。
+ */
+declare const installable: InstallableVueAliplayerV2;
+export { installable as VueAliplayerV2 };
+export default installable;
+//# sourceMappingURL=index.d.ts.map
--- a/lib/vue-aliplayer-v2.common.js
+++ b/lib/vue-aliplayer-v2.common.js
--- a/lib/vue-aliplayer-v2.css
+++ b/lib/vue-aliplayer-v2.css
@ -0,0 +1,2 @@
+.vue-aliplayer-v2[data-v-eff69876]{width:100%}
+/*$vite$:1*/
--- a/lib/vue-aliplayer-v2.js
+++ b/lib/vue-aliplayer-v2.js
@ -0,0 +1,395 @@
+import { computed as e, createElementBlock as t, defineComponent as n, nextTick as r, onBeforeUnmount as i, onMounted as a, openBlock as o, ref as s, watch as c } from "vue";
+//#region packages/AliplayerV2/sdkLoader.ts
+var l = "2.37.0", u = `https://g.alicdn.com/apsara-media-box/imp-web-player/${l}/skins/default/aliplayer-min.css`, d = `https://g.alicdn.com/apsara-media-box/imp-web-player/${l}/aliplayer-min.js`, f = /* @__PURE__ */ new Map();
+function p(e) {
+	return `https://g.alicdn.com/apsara-media-box/imp-web-player/${e}/skins/default/aliplayer-min.css`;
+}
+function m(e) {
+	return `https://g.alicdn.com/apsara-media-box/imp-web-player/${e}/aliplayer-min.js`;
+}
+function h(e) {
+	if (!e || document.querySelector(`link[data-vue-aliplayer-v2-css="${e}"]`)) return;
+	let t = document.createElement("link");
+	t.type = "text/css", t.rel = "stylesheet", t.href = e, t.dataset.vueAliplayerV2Css = e, document.head.appendChild(t);
+}
+function g(e, t) {
+	if (!e || t && window[t]) return Promise.resolve();
+	if (f.has(e)) return f.get(e);
+	let n = document.querySelector(`script[data-vue-aliplayer-v2-js="${e}"]`);
+	if (n) {
+		let t = new Promise((t, r) => {
+			if (n.dataset.vueAliplayerV2Loaded === "true") {
+				t();
+				return;
+			}
+			n.addEventListener("load", () => {
+				n.dataset.vueAliplayerV2Loaded = "true", t();
+			}, { once: !0 }), n.addEventListener("error", () => r(/* @__PURE__ */ Error(`Failed to load Aliplayer SDK: ${e}`)), { once: !0 });
+		});
+		return f.set(e, t), t;
+	}
+	let r = new Promise((t, n) => {
+		let r = document.createElement("script");
+		r.type = "text/javascript", r.src = e, r.dataset.vueAliplayerV2Js = e, r.addEventListener("load", () => {
+			r.dataset.vueAliplayerV2Loaded = "true", t();
+		}, { once: !0 }), r.addEventListener("error", () => n(/* @__PURE__ */ Error(`Failed to load Aliplayer SDK: ${e}`)), { once: !0 }), document.documentElement.appendChild(r);
+	});
+	return f.set(e, r), r;
+}
+async function _(e, t) {
+	h(e), await g(t, "Aliplayer");
+}
+async function v(e = []) {
+	for (let t of e) await g(t);
+}
+//#endregion
+//#region packages/AliplayerV2/source.ts
+var y = [
+	"m3u8",
+	"flv",
+	"mp4",
+	"rtmp",
+	"mp3"
+];
+function b(e) {
+	if (!e) return null;
+	if (/^rtmps?:\/\//i.test(e)) return "rtmp";
+	let t = e.split("?")[0].split("#")[0].toLowerCase();
+	return y.find((e) => e && t.endsWith(`.${e}`)) || null;
+}
+function x(e) {
+	if (!e) return e || null;
+	if (/^(data|blob):/i.test(e)) return e;
+	try {
+		return encodeURI(e);
+	} catch {
+		return e;
+	}
+}
+//#endregion
+//#region packages/AliplayerV2/tracking.ts
+var S = ["videocloud.cn-hangzhou.log.aliyuncs.com/logstores/newplayer/track"], C = !1;
+function w(e, t) {
+	return t.some((t) => typeof t == "string" ? e.includes(t) : t.test(e));
+}
+function T(e = S) {
+	if (C) return;
+	C = !0;
+	let t = window.fetch?.bind(window);
+	t && (window.fetch = ((n, r) => w(typeof n == "string" || n instanceof URL ? String(n) : n.url, e) ? Promise.resolve(new Response(null, {
+		status: 204,
+		statusText: "No Content"
+	})) : t(n, r)));
+	let n = XMLHttpRequest.prototype.open, r = XMLHttpRequest.prototype.send;
+	XMLHttpRequest.prototype.open = function(t, r, i, a, o) {
+		this.__vueAliplayerV2Blocked = w(String(r), e), n.call(this, t, r, i ?? !0, a ?? void 0, o ?? void 0);
+	}, XMLHttpRequest.prototype.send = function(e) {
+		this.__vueAliplayerV2Blocked || r.call(this, e);
+	};
+}
+//#endregion
+//#region packages/AliplayerV2/index.vue
+var E = /* @__PURE__ */ ((e, t) => {
+	let n = e.__vccOpts || e;
+	for (let [e, r] of t) n[e] = r;
+	return n;
+})(/* @__PURE__ */ n({
+	name: "VueAliplayerV2",
+	__name: "index",
+	props: {
+		autoFormat: {
+			type: Boolean,
+			default: !0
+		},
+		forbidFastForward: {
+			type: Boolean,
+			default: !1
+		},
+		license: { default: null },
+		lowLatency: {
+			type: Boolean,
+			default: !1
+		},
+		normalizeSourceUrl: {
+			type: Boolean,
+			default: !0
+		},
+		options: { default: null },
+		source: { default: null },
+		sdkVersion: { default: l },
+		cssLink: { default: "" },
+		scriptSrc: { default: "" },
+		componentScripts: { default: () => [] },
+		disableTracking: {
+			type: Boolean,
+			default: !1
+		},
+		trackingUrlPatterns: { default: () => [] }
+	},
+	emits: [
+		"ready",
+		"play",
+		"pause",
+		"canplay",
+		"playing",
+		"ended",
+		"liveStreamStop",
+		"onM3u8Retry",
+		"hideBar",
+		"showBar",
+		"waiting",
+		"timeupdate",
+		"snapshoted",
+		"requestFullScreen",
+		"cancelFullScreen",
+		"error",
+		"startSeek",
+		"completeSeek",
+		"sdk-error"
+	],
+	setup(n, { expose: l, emit: f }) {
+		let h = n, g = f, y = s(null), S = s(null), C = s(!1), w = s(null), E = 0, D = `player-${Math.random().toString(36).slice(2).toUpperCase()}`, O = [
+			"ready",
+			"play",
+			"pause",
+			"canplay",
+			"playing",
+			"ended",
+			"liveStreamStop",
+			"onM3u8Retry",
+			"hideBar",
+			"showBar",
+			"waiting",
+			"timeupdate",
+			"snapshoted",
+			"requestFullScreen",
+			"cancelFullScreen",
+			"error",
+			"startSeek",
+			"completeSeek"
+		], k = e(() => h.cssLink || (h.sdkVersion ? p(h.sdkVersion) : u)), A = e(() => h.scriptSrc || (h.sdkVersion ? m(h.sdkVersion) : d)), j = e(() => h.normalizeSourceUrl ? x(h.source) : h.source), M = e(() => b(j.value)), N = e(() => {
+			let e = {
+				width: "100%",
+				autoplay: !0,
+				...h.options || {},
+				...h.license ? { license: h.license } : {},
+				...j.value ? { source: j.value } : {},
+				id: D
+			};
+			return h.autoFormat && M.value && !e.format && (e.format = M.value), h.lowLatency && e.isLive && M.value === "flv" && (e.enableStashBufferForFlv = e.enableStashBufferForFlv ?? !1, e.stashInitialSizeForFlv = e.stashInitialSizeForFlv ?? 128), e;
+		});
+		function P() {
+			return y.value;
+		}
+		function F() {
+			y.value && (y.value.dispose(), y.value = null, w.value = null);
+		}
+		function I(e) {
+			O.forEach((t) => {
+				e.on(t, (e) => {
+					g(t, e);
+				});
+			});
+		}
+		function L(e) {
+			if (!h.forbidFastForward) return;
+			let t = 0, n = 0;
+			e.on("timeupdate", () => {
+				let r = e.getCurrentTime();
+				if (r - t > 2) {
+					e.seek(t);
+					return;
+				}
+				t = r, t >= n && (n = t);
+			});
+		}
+		function R() {
+			if (C.value || !window.Aliplayer || !S.value) return;
+			F();
+			let e = window.Aliplayer({ ...N.value });
+			y.value = e, w.value = M.value, I(e), L(e);
+		}
+		async function z() {
+			let e = ++E;
+			try {
+				if (h.disableTracking && T(h.trackingUrlPatterns.length ? h.trackingUrlPatterns : void 0), await _(k.value, A.value), await v(h.componentScripts), await r(), C.value || e !== E) return;
+				R();
+			} catch (e) {
+				g("sdk-error", e instanceof Error ? e : Error(String(e)));
+			}
+		}
+		async function B(e) {
+			if (e && y.value) {
+				y.value.loadByUrl(h.normalizeSourceUrl && x(e) || e);
+				return;
+			}
+			await z();
+		}
+		async function V(e) {
+			await B(e);
+		}
+		function H() {
+			y.value?.play();
+		}
+		function U() {
+			y.value?.pause();
+		}
+		function W() {
+			y.value?.replay();
+		}
+		function G(e) {
+			y.value?.seek(e);
+		}
+		function K() {
+			return y.value?.getCurrentTime();
+		}
+		function ee() {
+			return y.value?.getDuration();
+		}
+		function q() {
+			return y.value?.getVolume();
+		}
+		function J(e) {
+			y.value?.setVolume(e);
+		}
+		function Y(e, t) {
+			y.value?.loadByUrl(e, t);
+		}
+		function X(e, t) {
+			y.value?.replayByVidAndPlayAuth(e, t);
+		}
+		function Z(e, t, n, r, i, a) {
+			y.value?.replayByVidAndAuthInfo(e, t, n, r, i, a);
+		}
+		function Q(e, t) {
+			y.value?.setPlayerSize(e, t);
+		}
+		function $(e) {
+			y.value?.setSpeed(e);
+		}
+		function te(e, t, n) {
+			y.value?.setSanpshotProperties(e, t, n);
+		}
+		function ne() {
+			y.value?.fullscreenService?.requestFullScreen();
+		}
+		function re() {
+			y.value?.fullscreenService?.cancelFullScreen();
+		}
+		function ie() {
+			return y.value?.fullscreenService?.getIsFullScreen();
+		}
+		function ae() {
+			return y.value?.getStatus();
+		}
+		function oe(e, t) {
+			y.value?.liveShiftSerivce?.setLiveTimeRange(e, t);
+		}
+		function se(e) {
+			y.value?.setRotate(e);
+		}
+		function ce() {
+			return y.value?.getRotate();
+		}
+		function le(e) {
+			y.value?.setImage(e);
+		}
+		function ue(e) {
+			y.value?.setCover(e);
+		}
+		function de(e) {
+			y.value?.setProgressMarkers(e);
+		}
+		function fe(e) {
+			y.value?.setPreviewTime(e);
+		}
+		function pe() {
+			return y.value?.getPreviewTime();
+		}
+		function me() {
+			return y.value?.isPreview();
+		}
+		function he(e, t) {
+			y.value?.off?.(e, t);
+		}
+		return a(() => {
+			z();
+		}), c(() => j.value, (e) => {
+			if (!e) return;
+			let t = b(e);
+			if (y.value && t && t === w.value) {
+				y.value.loadByUrl(e);
+				return;
+			}
+			z();
+		}), c(() => [
+			h.options,
+			h.forbidFastForward,
+			h.license,
+			h.lowLatency,
+			h.autoFormat,
+			h.sdkVersion,
+			h.cssLink,
+			h.scriptSrc,
+			h.componentScripts,
+			h.disableTracking,
+			h.trackingUrlPatterns
+		], () => {
+			z();
+		}, { deep: !0 }), i(() => {
+			C.value = !0, E += 1, F();
+		}), l({
+			getPlayer: P,
+			init: z,
+			initPlayer: R,
+			reload: B,
+			retry: V,
+			play: H,
+			pause: U,
+			replay: W,
+			seek: G,
+			getCurrentTime: K,
+			getDuration: ee,
+			getVolume: q,
+			setVolume: J,
+			loadByUrl: Y,
+			replayByVidAndPlayAuth: X,
+			replayByVidAndAuthInfo: Z,
+			setPlayerSize: Q,
+			setSpeed: $,
+			setSanpshotProperties: te,
+			requestFullScreen: ne,
+			cancelFullScreen: re,
+			getIsFullScreen: ie,
+			getStatus: ae,
+			setLiveTimeRange: oe,
+			setRotate: se,
+			getRotate: ce,
+			setImage: le,
+			dispose: F,
+			setCover: ue,
+			setProgressMarkers: de,
+			setPreviewTime: fe,
+			getPreviewTime: pe,
+			isPreview: me,
+			off: he
+		}), (e, n) => (o(), t("div", {
+			id: D,
+			ref_key: "containerRef",
+			ref: S,
+			class: "vue-aliplayer-v2"
+		}, null, 512));
+	}
+}), [["__scopeId", "data-v-eff69876"]]), D = {
+	sdkVersion: l,
+	cssLink: u,
+	scriptSrc: d,
+	componentScripts: [],
+	disableTracking: !1,
+	trackingUrlPatterns: []
+}, O = E;
+O.install = (e, t) => {
+	Object.assign(D, t || {}), e.component("VueAliplayerV2", O);
+}, O.props.cssLink.default = () => D.cssLink, O.props.scriptSrc.default = () => D.scriptSrc, O.props.sdkVersion.default = () => D.sdkVersion, O.props.componentScripts.default = () => D.componentScripts, O.props.disableTracking.default = () => D.disableTracking, O.props.trackingUrlPatterns.default = () => D.trackingUrlPatterns, O.Player = O;
+//#endregion
+export { O as VueAliplayerV2, O as default };
--- a/lib/vue-aliplayer-v2.umd.cjs
+++ b/lib/vue-aliplayer-v2.umd.cjs
--- a/lib/vue-aliplayer-v2.umd.js
+++ b/lib/vue-aliplayer-v2.umd.js
--- a/lib/vue-aliplayer-v2.umd.min.js
+++ b/lib/vue-aliplayer-v2.umd.min.js
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@ -1,31 +1,42 @@
 {
    "name": "vue-aliplayer-v2",
-    "version": "1.3.1",
+    "version": "2.0.0",
+    "type": "module",
    "author": "yxs",
-    "description": "感谢每一位支持开源的朋友. 这是一个基于Alipayer 开发并封装成vue组件的集成播放器.可播放rtmp,m3u8,mp4....视频.除支持直播流与点播的基础功能外,也支持视频的加密播放、清晰度切换、直播时移等业务场景",
-    "main": "lib/vue-aliplayer-v2.umd.min.js",
+    "description": "Vue 3 wrapper for Aliyun Aliplayer. Supports mp4, m3u8, flv, live streams, encrypted playback, quality switching, and live time shift through the official Aliplayer SDK.",
+    "main": "lib/vue-aliplayer-v2.umd.cjs",
+    "module": "lib/vue-aliplayer-v2.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "import": "./lib/vue-aliplayer-v2.js",
+            "require": "./lib/vue-aliplayer-v2.umd.cjs"
+        }
+    },
+    "files": [
+        "lib",
+        "README.md",
+        "README.en-US.md"
+    ],
    "private": false,
    "license": "MIT",
    "scripts": {
-        "dev": "vue-cli-service serve",
-        "build": "vue-cli-service build",
-        "lint": "vue-cli-service lint",
-        "lib": "vue-cli-service build --target lib --name vue-aliplayer-v2 --dest lib packages/index.js"
+        "dev": "vite --host 0.0.0.0",
+        "build": "vite build --mode demo",
+        "type-check": "vue-tsc --noEmit",
+        "lib": "vue-tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --outDir lib/types && vite build --mode lib",
+        "lint": "vue-tsc --noEmit"
    },
    "dependencies": {
-        "core-js": "^2.6.5",
-        "vue": "^2.6.10"
+        "vue": "^3.5.34"
    },
    "devDependencies": {
-        "@vue/cli-plugin-babel": "^3.8.0",
-        "@vue/cli-plugin-eslint": "^3.8.0",
-        "@vue/cli-service": "^3.8.0",
-        "babel-eslint": "^10.0.1",
-        "eslint": "^5.16.0",
-        "eslint-plugin-vue": "^5.0.0",
-        "less": "^3.9.0",
-        "less-loader": "^5.0.0",
-        "vue-template-compiler": "^2.6.10"
+        "@types/node": "^24.10.0",
+        "@vitejs/plugin-vue": "^6.0.7",
+        "typescript": "^5.9.3",
+        "vite": "^8.0.14",
+        "vue-tsc": "^3.3.1"
    },
    "repository": {
        "type": "git",
--- a/packages/AliplayerV2/index.vue
+++ b/packages/AliplayerV2/index.vue
--- a/packages/AliplayerV2/sdkLoader.ts
+++ b/packages/AliplayerV2/sdkLoader.ts
@ -0,0 +1,140 @@
+/**
+ * 默认阿里云 Web 播放器 SDK 版本。
+ *
+ * 该版本来自阿里云播放器 SDK 下载页。后续升级默认 SDK 时，只需要同步修改该常量。
+ */
+export const DEFAULT_SDK_VERSION = '2.37.0';
+
+/**
+ * 默认 Aliplayer CSS 地址。
+ *
+ * 2.16.3 之后阿里云官方资源路径从 `de/prismplayer` 切换到了
+ * `apsara-media-box/imp-web-player`，因此这里使用新路径。
+ */
+export const DEFAULT_CSS_LINK = `https://g.alicdn.com/apsara-media-box/imp-web-player/${DEFAULT_SDK_VERSION}/skins/default/aliplayer-min.css`;
+
+/**
+ * 默认 Aliplayer JS 地址。
+ */
+export const DEFAULT_SCRIPT_SRC = `https://g.alicdn.com/apsara-media-box/imp-web-player/${DEFAULT_SDK_VERSION}/aliplayer-min.js`;
+
+/**
+ * 脚本加载 Promise 缓存。
+ *
+ * 同一个页面可能同时存在多个播放器实例，或者组件在路由切换中频繁挂载卸载。
+ * 缓存可以避免重复插入相同的 `<script>` 标签，也避免多个实例并发等待时产生竞态。
+ */
+const scriptLoadPromises = new Map<string, Promise<void>>();
+
+/**
+ * 根据 SDK 版本生成官方 CSS 地址。
+ *
+ * @param version 阿里云 Web 播放器 SDK 版本号。
+ * @returns 官方 `imp-web-player` CSS 资源地址。
+ */
+export function getCssLinkByVersion(version: string): string {
+    return `https://g.alicdn.com/apsara-media-box/imp-web-player/${version}/skins/default/aliplayer-min.css`;
+}
+
+/**
+ * 根据 SDK 版本生成官方 JS 地址。
+ *
+ * @param version 阿里云 Web 播放器 SDK 版本号。
+ * @returns 官方 `imp-web-player` JS 资源地址。
+ */
+export function getScriptSrcByVersion(version: string): string {
+    return `https://g.alicdn.com/apsara-media-box/imp-web-player/${version}/aliplayer-min.js`;
+}
+
+/**
+ * 确保页面中已经存在指定 Aliplayer CSS。
+ *
+ * @param cssLink CSS 资源地址。为空时不做任何操作。
+ */
+function ensureStylesheet(cssLink: string): void {
+    if (!cssLink) return;
+
+    const existed = document.querySelector<HTMLLinkElement>(`link[data-vue-aliplayer-v2-css="${cssLink}"]`);
+    if (existed) return;
+
+    const link = document.createElement('link');
+    link.type = 'text/css';
+    link.rel = 'stylesheet';
+    link.href = cssLink;
+    link.dataset.vueAliplayerV2Css = cssLink;
+    document.head.appendChild(link);
+}
+
+/**
+ * 确保页面中已经加载指定脚本。
+ *
+ * @param scriptSrc 脚本资源地址。为空时直接视为加载完成。
+ * @param globalName 可选的全局变量名。如果该全局变量已经存在，说明对应脚本已经可用。
+ * @returns 脚本加载完成 Promise。
+ */
+function ensureScript(scriptSrc: string, globalName?: string): Promise<void> {
+    if (!scriptSrc) return Promise.resolve();
+    if (globalName && window[globalName]) return Promise.resolve();
+    if (scriptLoadPromises.has(scriptSrc)) return scriptLoadPromises.get(scriptSrc) as Promise<void>;
+
+    const existed = document.querySelector<HTMLScriptElement>(`script[data-vue-aliplayer-v2-js="${scriptSrc}"]`);
+    if (existed) {
+        const loadPromise = new Promise<void>((resolve, reject) => {
+            if (existed.dataset.vueAliplayerV2Loaded === 'true') {
+                resolve();
+                return;
+            }
+            existed.addEventListener('load', () => {
+                existed.dataset.vueAliplayerV2Loaded = 'true';
+                resolve();
+            }, { once: true });
+            existed.addEventListener('error', () => reject(new Error(`Failed to load Aliplayer SDK: ${scriptSrc}`)), { once: true });
+        });
+        scriptLoadPromises.set(scriptSrc, loadPromise);
+        return loadPromise;
+    }
+
+    const loadPromise = new Promise<void>((resolve, reject) => {
+        const script = document.createElement('script');
+        script.type = 'text/javascript';
+        script.src = scriptSrc;
+        script.dataset.vueAliplayerV2Js = scriptSrc;
+        script.addEventListener('load', () => {
+            script.dataset.vueAliplayerV2Loaded = 'true';
+            resolve();
+        }, { once: true });
+        script.addEventListener('error', () => reject(new Error(`Failed to load Aliplayer SDK: ${scriptSrc}`)), { once: true });
+        document.documentElement.appendChild(script);
+    });
+
+    scriptLoadPromises.set(scriptSrc, loadPromise);
+    return loadPromise;
+}
+
+/**
+ * 加载 Aliplayer SDK 的 CSS 和 JS。
+ *
+ * 该方法会先插入 CSS，再等待 JS 加载完成。它会复用已有标签和加载 Promise，
+ * 因而可以安全地被多个播放器实例同时调用。
+ *
+ * @param cssLink Aliplayer 样式地址。
+ * @param scriptSrc Aliplayer 脚本地址。
+ */
+export async function loadAliplayerSdk(cssLink: string, scriptSrc: string): Promise<void> {
+    ensureStylesheet(cssLink);
+    await ensureScript(scriptSrc, 'Aliplayer');
+}
+
+/**
+ * 按顺序加载额外扩展脚本。
+ *
+ * 主要用于 Aliplayer 自定义组件，例如播放列表、跑马灯、水印等。顺序加载能保证
+ * 后一个脚本可以依赖前一个脚本暴露的全局对象。
+ *
+ * @param scriptUrls 需要在播放器初始化前加载的脚本地址列表。
+ */
+export async function loadExtraScripts(scriptUrls: string[] = []): Promise<void> {
+    for (const scriptUrl of scriptUrls) {
+        await ensureScript(scriptUrl);
+    }
+}
--- a/packages/AliplayerV2/source.ts
+++ b/packages/AliplayerV2/source.ts
@ -0,0 +1,50 @@
+/**
+ * 组件可以从播放地址中推断出的媒体格式。
+ *
+ * `null` 表示无法可靠判断格式，组件会把格式判断交给 Aliplayer SDK。
+ */
+export type SourceFormat = 'mp4' | 'm3u8' | 'flv' | 'rtmp' | 'mp3' | null;
+
+/**
+ * 根据文件后缀可自动识别的格式列表。
+ */
+const KNOWN_FORMATS: SourceFormat[] = ['m3u8', 'flv', 'mp4', 'rtmp', 'mp3'];
+
+/**
+ * 从播放地址推断媒体格式。
+ *
+ * 推断逻辑会忽略 query 和 hash，仅根据协议或路径后缀判断。RTMP 地址优先根据协议识别，
+ * 其他格式根据后缀识别。
+ *
+ * @param source 播放源地址。
+ * @returns 推断出的媒体格式；无法判断时返回 `null`。
+ */
+export function inferSourceFormat(source?: string | null): SourceFormat {
+    if (!source) return null;
+
+    if (/^rtmps?:\/\//i.test(source)) return 'rtmp';
+
+    const cleanSource = source.split('?')[0].split('#')[0].toLowerCase();
+    const matched = KNOWN_FORMATS.find((format) => format && cleanSource.endsWith(`.${format}`));
+    return matched || null;
+}
+
+/**
+ * 标准化播放源 URL。
+ *
+ * 目前只做 `encodeURI`，用于处理中文文件名、空格等常见未编码地址。`data:` 和 `blob:`
+ * 地址不应该被编码，因此会原样返回。若浏览器环境对某些非法 URL 抛错，也会回退到原始地址。
+ *
+ * @param source 播放源地址。
+ * @returns 标准化后的地址；空值保持为空。
+ */
+export function normalizeSource(source?: string | null): string | null {
+    if (!source) return source || null;
+    if (/^(data|blob):/i.test(source)) return source;
+
+    try {
+        return encodeURI(source);
+    } catch {
+        return source;
+    }
+}
--- a/packages/AliplayerV2/tracking.ts
+++ b/packages/AliplayerV2/tracking.ts
@ -0,0 +1,80 @@
+/**
+ * 默认拦截的阿里云播放器统计上报地址片段。
+ *
+ * 这是根据历史 issue 中用户反馈的 `newplayer/track` 请求整理的兜底规则。
+ */
+const DEFAULT_TRACKING_PATTERNS: Array<string | RegExp> = [
+    'videocloud.cn-hangzhou.log.aliyuncs.com/logstores/newplayer/track'
+];
+
+/**
+ * 标记统计拦截器是否已经安装。
+ *
+ * 拦截器会 monkey patch `fetch` 和 `XMLHttpRequest`，同一页面只应安装一次。
+ */
+let trackingBlockerInstalled = false;
+
+/**
+ * 判断 URL 是否命中需要拦截的统计规则。
+ *
+ * @param url 请求地址。
+ * @param patterns 字符串片段或正则列表。
+ * @returns 命中任意规则时返回 `true`。
+ */
+function matchesTrackingUrl(url: string, patterns: Array<string | RegExp>): boolean {
+    return patterns.some((pattern) => {
+        if (typeof pattern === 'string') return url.includes(pattern);
+        return pattern.test(url);
+    });
+}
+
+/**
+ * 安装 Aliplayer 统计请求拦截器。
+ *
+ * 该方法会拦截命中规则的 `fetch` 和 `XMLHttpRequest` 请求，避免向已知统计地址发送数据。
+ * 这是 wrapper 层提供的可选缓解方案，不替代阿里云官方 SDK 的开关能力。由于它会修改全局
+ * 网络 API，只有在用户显式设置 `disableTracking` 时才会调用。
+ *
+ * @param patterns 需要拦截的 URL 片段或正则。不传时使用默认已知统计地址。
+ */
+export function installTrackingBlocker(patterns: Array<string | RegExp> = DEFAULT_TRACKING_PATTERNS): void {
+    if (trackingBlockerInstalled) return;
+    trackingBlockerInstalled = true;
+
+    const originalFetch = window.fetch?.bind(window);
+    if (originalFetch) {
+        window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+            const url = typeof input === 'string' || input instanceof URL ? String(input) : input.url;
+            if (matchesTrackingUrl(url, patterns)) {
+                return Promise.resolve(new Response(null, { status: 204, statusText: 'No Content' }));
+            }
+            return originalFetch(input, init);
+        }) as typeof window.fetch;
+    }
+
+    const originalOpen = XMLHttpRequest.prototype.open;
+    const originalSend = XMLHttpRequest.prototype.send;
+
+    XMLHttpRequest.prototype.open = function open(method: string, url: string | URL, async?: boolean, username?: string | null, password?: string | null): void {
+        this.__vueAliplayerV2Blocked = matchesTrackingUrl(String(url), patterns);
+        originalOpen.call(this, method, url, async ?? true, username ?? undefined, password ?? undefined);
+    };
+
+    XMLHttpRequest.prototype.send = function send(body?: Document | XMLHttpRequestBodyInit | null): void {
+        if (this.__vueAliplayerV2Blocked) {
+            return;
+        }
+        originalSend.call(this, body);
+    };
+}
+
+declare global {
+    interface XMLHttpRequest {
+        /**
+         * 当前 XHR 是否命中 vue-aliplayer-v2 的统计拦截规则。
+         *
+         * 这是内部标记字段，仅用于 `open` 和 `send` 两个 patch 方法之间传递状态。
+         */
+        __vueAliplayerV2Blocked?: boolean;
+    }
+}
--- a/packages/AliplayerV2/types.ts
+++ b/packages/AliplayerV2/types.ts
@ -0,0 +1,567 @@
+import type { Plugin } from 'vue';
+
+/**
+ * 全局插件安装配置。
+ *
+ * 这些配置会作为组件 props 的默认值使用，适合在 `app.use(VueAliplayerV2, options)` 时
+ * 统一声明 SDK 版本、资源地址和公共扩展行为。单个组件仍然可以通过同名 props 覆盖这些默认值。
+ */
+export interface VueAliplayerV2Options {
+    /**
+     * 阿里云 Web 播放器 SDK 版本号。
+     *
+     * 当 `cssLink` 或 `scriptSrc` 未显式传入时，组件会根据该版本号生成官方
+     * `apsara-media-box/imp-web-player` 资源地址。
+     */
+    sdkVersion?: string;
+    /**
+     * Aliplayer CSS 资源地址。
+     *
+     * 显式传入后优先级高于 `sdkVersion` 自动生成的地址。
+     */
+    cssLink?: string;
+    /**
+     * Aliplayer JS 资源地址。
+     *
+     * 显式传入后优先级高于 `sdkVersion` 自动生成的地址。
+     */
+    scriptSrc?: string;
+    /**
+     * 自定义组件或业务扩展脚本地址列表。
+     *
+     * 组件会在创建播放器实例前按顺序加载这些脚本，适合接入播放列表、跑马灯、
+     * 自定义水印等 Aliplayer 自定义组件。
+     */
+    componentScripts?: string[];
+    /**
+     * 是否启用已知 Aliplayer 统计上报拦截。
+     *
+     * 该能力是 wrapper 层的可选兜底方案，优先建议使用阿里云官方配置项。
+     */
+    disableTracking?: boolean;
+    /**
+     * 需要拦截的统计上报 URL 片段或正则。
+     *
+     * 默认只拦截已知的 `newplayer/track` 地址；传入该字段可扩展业务侧发现的其他上报地址。
+     */
+    trackingUrlPatterns?: Array<string | RegExp>;
+}
+
+/**
+ * `<VueAliplayerV2 />` 组件 props。
+ *
+ * 除了播放器业务配置外，还继承了全局插件配置，使每个组件实例都可以单独覆盖 SDK
+ * 版本、资源地址、扩展脚本和统计拦截策略。
+ */
+export interface AliplayerV2Props extends VueAliplayerV2Options {
+    /**
+     * 是否根据 `source` 后缀自动推断 `format`。
+     *
+     * 支持 `mp4`、`m3u8`、`flv`、`mp3`、`rtmp`。当 `options.format` 已设置时，
+     * 组件不会覆盖用户显式传入的格式。
+     */
+    autoFormat?: boolean;
+    /**
+     * 是否禁止用户拖拽快进。
+     *
+     * 开启后组件会监听 `timeupdate`，当检测到播放位置向前跳跃超过阈值时回退到上一次位置。
+     */
+    forbidFastForward?: boolean;
+    /**
+     * Aliplayer License 配置。
+     *
+     * 新版阿里云 Web 播放器要求业务域名绑定 License。该字段会合并到最终的
+     * Aliplayer 初始化 options 中，优先级高于全局配置，等价于 `options.license`。
+     */
+    license?: AliplayerLicense | null;
+    /**
+     * 是否启用 FLV 直播低延迟预设。
+     *
+     * 当 `options.isLive` 为 `true` 且推断格式为 `flv` 时，组件会默认关闭 FLV stash buffer
+     * 并设置较小的初始缓存。用户仍可在 `options` 中显式覆盖这些字段。
+     */
+    lowLatency?: boolean;
+    /**
+     * 是否对播放源 URL 执行 `encodeURI`。
+     *
+     * 用于处理中文文件名、空格等未编码 URL。`data:` 和 `blob:` 地址会被原样保留。
+     */
+    normalizeSourceUrl?: boolean;
+    /**
+     * 透传给 Aliplayer 的原始初始化配置。
+     *
+     * 组件只会补充必要的 `id`、`source`、`license`、`format` 和低延迟默认值，
+     * 其他字段全部保持透传。
+     */
+    options?: AliplayerOptions | null;
+    /**
+     * 播放源 URL。
+     *
+     * 存在时优先于 `options.source`。同格式切换时优先调用 `loadByUrl`，跨格式切换时会重建播放器。
+     */
+    source?: string | null;
+}
+
+/**
+ * 阿里云 Web 播放器 License 信息。
+ */
+export interface AliplayerLicense {
+    /**
+     * 申请 License 时绑定的网站域名。
+     */
+    domain: string;
+    /**
+     * 阿里云控制台生成的 License Key。
+     */
+    key: string;
+}
+
+/**
+ * 当前组件会透传的 Aliplayer 事件名。
+ */
+export type AliplayerEventName =
+    | 'ready'
+    | 'play'
+    | 'pause'
+    | 'canplay'
+    | 'playing'
+    | 'ended'
+    | 'liveStreamStop'
+    | 'onM3u8Retry'
+    | 'hideBar'
+    | 'showBar'
+    | 'waiting'
+    | 'timeupdate'
+    | 'snapshoted'
+    | 'requestFullScreen'
+    | 'cancelFullScreen'
+    | 'error'
+    | 'startSeek'
+    | 'completeSeek';
+
+/**
+ * Aliplayer 初始化配置。
+ *
+ * 这里只声明 wrapper 中常用和文档中重点暴露的字段。阿里云 SDK 的配置项较多，
+ * 因此保留索引签名以允许业务侧继续传入官方新增或未显式列出的参数。
+ */
+export interface AliplayerOptions {
+    /**
+     * 播放器容器 DOM id。组件内部会自动生成并覆盖该字段。
+     */
+    id?: string;
+    /**
+     * 播放源 URL。
+     */
+    source?: string;
+    /**
+     * 播放器宽度，例如 `100%` 或 `640px`。
+     */
+    width?: string;
+    /**
+     * 是否自动播放。
+     */
+    autoplay?: boolean;
+    /**
+     * 是否为直播流。
+     */
+    isLive?: boolean;
+    /**
+     * 播放源格式，例如 `mp4`、`m3u8`、`flv`。
+     */
+    format?: string;
+    /**
+     * Aliplayer License 配置。
+     */
+    license?: AliplayerLicense;
+    /**
+     * 点播视频 ID，用于 VID + PlayAuth 或 STS 播放。
+     */
+    vid?: string;
+    /**
+     * 点播播放凭证。
+     */
+    playauth?: string;
+    /**
+     * STS 临时 AccessKey ID。
+     */
+    accessKeyId?: string;
+    /**
+     * STS 安全令牌。
+     */
+    securityToken?: string;
+    /**
+     * STS 临时 AccessKey Secret。
+     */
+    accessKeySecret?: string;
+    /**
+     * 媒资所在地域，例如 `cn-shanghai`。
+     */
+    region?: string;
+    /**
+     * 播放地址有效时长，单位秒。
+     */
+    authTimeout?: number;
+    /**
+     * Aliplayer 自定义组件配置。
+     */
+    components?: unknown[];
+    /**
+     * FLV 直播是否启用 stash buffer。
+     */
+    enableStashBufferForFlv?: boolean;
+    /**
+     * FLV 初始缓存大小。
+     */
+    stashInitialSizeForFlv?: number;
+    /**
+     * RTS SDK 版本号。
+     */
+    rtsVersion?: string;
+    /**
+     * 允许传入阿里云播放器官方新增字段或业务侧自定义字段。
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Aliplayer 全屏服务对象。
+ */
+export interface AliplayerFullscreenService {
+    /**
+     * 进入全屏。
+     */
+    requestFullScreen: () => void;
+    /**
+     * 退出全屏。
+     */
+    cancelFullScreen: () => void;
+    /**
+     * 获取当前是否处于全屏状态。
+     */
+    getIsFullScreen: () => boolean;
+}
+
+/**
+ * Aliplayer 直播时移服务对象。
+ */
+export interface AliplayerLiveShiftService {
+    /**
+     * 设置直播时移的可播放时间范围。
+     *
+     * @param beginTime 起始时间，通常为 `YYYY/MM/DD HH:mm:ss`。
+     * @param endTime 结束时间，通常为 `YYYY/MM/DD HH:mm:ss`。
+     */
+    setLiveTimeRange: (beginTime: string, endTime: string) => void;
+}
+
+/**
+ * Aliplayer 播放器实例。
+ *
+ * 该接口描述组件会调用或暴露的底层 SDK 方法，并非阿里云播放器完整类型定义。
+ */
+export interface AliplayerInstance {
+    /**
+     * 监听底层播放器事件。
+     *
+     * @param eventName 事件名。
+     * @param handler 事件回调。
+     */
+    on: (eventName: string, handler: (event?: unknown) => void) => void;
+    /**
+     * 取消监听底层播放器事件。
+     *
+     * 部分 SDK 版本可能没有该方法，因此这里声明为可选。
+     */
+    off?: (eventName: string, handler: (event?: unknown) => void) => void;
+    /**
+     * 播放视频。
+     */
+    play: () => void;
+    /**
+     * 暂停视频。
+     */
+    pause: () => void;
+    /**
+     * 从头重播视频。
+     */
+    replay: () => void;
+    /**
+     * 跳转到指定播放时间。
+     *
+     * @param time 秒数。
+     */
+    seek: (time: number) => void;
+    /**
+     * 获取当前播放时间，单位秒。
+     */
+    getCurrentTime: () => number;
+    /**
+     * 获取视频总时长，单位秒。
+     */
+    getDuration: () => number;
+    /**
+     * 获取当前音量，范围通常为 0 到 1。
+     */
+    getVolume: () => number;
+    /**
+     * 设置音量。
+     *
+     * @param volume 音量，范围通常为 0 到 1。
+     */
+    setVolume: (volume: number) => void;
+    /**
+     * 通过 URL 切换播放源。
+     *
+     * @param url 新播放地址。
+     * @param time 可选起播时间，单位秒。
+     */
+    loadByUrl: (url: string, time?: number) => void;
+    /**
+     * 使用 VID + PlayAuth 重新播放。
+     */
+    replayByVidAndPlayAuth: (vid: string, playauth: string) => void;
+    /**
+     * 使用 MPS 鉴权信息重新播放。
+     */
+    replayByVidAndAuthInfo: (
+        vid: string,
+        accId: string,
+        accSecret: string,
+        stsToken: string,
+        authInfo: string,
+        domainRegion: string
+    ) => void;
+    /**
+     * 设置播放器尺寸。
+     */
+    setPlayerSize: (width: string, height: string) => void;
+    /**
+     * 设置倍速。
+     */
+    setSpeed: (speed: number) => void;
+    /**
+     * 设置截图参数。
+     */
+    setSanpshotProperties: (width: number, height: number, rate: number) => void;
+    /**
+     * 全屏服务。
+     */
+    fullscreenService?: AliplayerFullscreenService;
+    /**
+     * 获取播放器状态。
+     */
+    getStatus: () => string;
+    /**
+     * 直播时移服务。字段名保留阿里云 SDK 原始拼写。
+     */
+    liveShiftSerivce?: AliplayerLiveShiftService;
+    /**
+     * 设置视频旋转角度。
+     */
+    setRotate: (rotate: number) => void;
+    /**
+     * 获取当前视频旋转角度。
+     */
+    getRotate: () => number;
+    /**
+     * 设置视频镜像。
+     */
+    setImage: (image: string) => void;
+    /**
+     * 销毁播放器实例并释放底层资源。
+     */
+    dispose: () => void;
+    /**
+     * 设置封面图。
+     */
+    setCover: (cover: string) => void;
+    /**
+     * 设置进度条打点。
+     */
+    setProgressMarkers: (markers: unknown[]) => void;
+    /**
+     * 设置试看时间。
+     */
+    setPreviewTime: (time: number) => void;
+    /**
+     * 获取试看时间。
+     */
+    getPreviewTime: () => number;
+    /**
+     * 判断当前是否处于试看状态。
+     */
+    isPreview: () => boolean;
+}
+
+/**
+ * 通过 Vue `ref` 暴露给业务代码调用的组件方法。
+ *
+ * 方法名基本保持 1.x 版本和阿里云 SDK 的命名，便于迁移旧项目和查阅官方文档。
+ */
+export interface VueAliplayerV2Expose {
+    /**
+     * 获取底层 Aliplayer 实例。
+     */
+    getPlayer: () => AliplayerInstance | null;
+    /**
+     * 加载 SDK 并初始化播放器。
+     */
+    init: () => Promise<void>;
+    /**
+     * 使用当前 props/options 立即创建播放器实例。
+     */
+    initPlayer: () => void;
+    /**
+     * 局部重载播放器。
+     *
+     * @param nextSource 可选的新播放地址。同格式地址会优先走底层 `loadByUrl`。
+     */
+    reload: (nextSource?: string) => Promise<void>;
+    /**
+     * 播放失败后的业务重试入口。
+     *
+     * 当前实现与 `reload` 等价，命名上更适合在 `error` 回调中使用。
+     */
+    retry: (nextSource?: string) => Promise<void>;
+    /**
+     * 播放视频。
+     */
+    play: () => void;
+    /**
+     * 暂停视频。
+     */
+    pause: () => void;
+    /**
+     * 从头重播视频。
+     */
+    replay: () => void;
+    /**
+     * 跳转到指定播放时间。
+     */
+    seek: (time: number) => void;
+    /**
+     * 获取当前播放时间。
+     */
+    getCurrentTime: () => number | undefined;
+    /**
+     * 获取视频总时长。
+     */
+    getDuration: () => number | undefined;
+    /**
+     * 获取当前音量。
+     */
+    getVolume: () => number | undefined;
+    /**
+     * 设置当前音量。
+     */
+    setVolume: (volume: number) => void;
+    /**
+     * 通过 URL 切换播放源。
+     */
+    loadByUrl: (url: string, time?: number) => void;
+    /**
+     * 使用 VID + PlayAuth 重新播放。
+     */
+    replayByVidAndPlayAuth: (vid: string, playauth: string) => void;
+    /**
+     * 使用 MPS 鉴权信息重新播放。
+     */
+    replayByVidAndAuthInfo: (
+        vid: string,
+        accId: string,
+        accSecret: string,
+        stsToken: string,
+        authInfo: string,
+        domainRegion: string
+    ) => void;
+    /**
+     * 设置播放器尺寸。
+     */
+    setPlayerSize: (width: string, height: string) => void;
+    /**
+     * 设置倍速。
+     */
+    setSpeed: (speed: number) => void;
+    /**
+     * 设置截图参数。
+     */
+    setSanpshotProperties: (width: number, height: number, rate: number) => void;
+    /**
+     * 进入全屏。
+     */
+    requestFullScreen: () => void;
+    /**
+     * 退出全屏。
+     */
+    cancelFullScreen: () => void;
+    /**
+     * 获取是否处于全屏状态。
+     */
+    getIsFullScreen: () => boolean | undefined;
+    /**
+     * 获取播放器状态。
+     */
+    getStatus: () => string | undefined;
+    /**
+     * 设置直播时移可播放范围。
+     */
+    setLiveTimeRange: (beginTime: string, endTime: string) => void;
+    /**
+     * 设置视频旋转角度。
+     */
+    setRotate: (rotate: number) => void;
+    /**
+     * 获取视频旋转角度。
+     */
+    getRotate: () => number | undefined;
+    /**
+     * 设置视频镜像。
+     */
+    setImage: (image: string) => void;
+    /**
+     * 销毁播放器实例。
+     */
+    dispose: () => void;
+    /**
+     * 设置封面图。
+     */
+    setCover: (cover: string) => void;
+    /**
+     * 设置进度条打点。
+     */
+    setProgressMarkers: (markers: unknown[]) => void;
+    /**
+     * 设置试看时间。
+     */
+    setPreviewTime: (time: number) => void;
+    /**
+     * 获取试看时间。
+     */
+    getPreviewTime: () => number | undefined;
+    /**
+     * 判断当前是否处于试看状态。
+     */
+    isPreview: () => boolean | undefined;
+    /**
+     * 取消监听底层播放器事件。
+     */
+    off: (eventName: string, handler: (event?: unknown) => void) => void;
+}
+
+/**
+ * 兼容 Vue 插件安装语义的组件类型。
+ */
+export type VueAliplayerV2Plugin = Plugin & {
+    /**
+     * 兼容 1.x 局部注册写法的组件别名。
+     */
+    Player?: unknown;
+};
+
+declare global {
+    interface Window {
+        Aliplayer?: (options: AliplayerOptions) => AliplayerInstance;
+        [key: string]: unknown;
+    }
+}
--- a/packages/index.js
+++ b/packages/index.js
@ -1,11 +0,0 @@
-// packages / index.js
-// 导入单个组件
-import VueAliplayerV2 from './AliplayerV2';
-// 定义 install 方法
-VueAliplayerV2.install = (Vue, options) =>{
-    if(options && options.cssLink) VueAliplayerV2.props.cssLink.default = options.cssLink;
-    if(options && options.scriptSrc) VueAliplayerV2.props.scriptSrc.default = options.scriptSrc;
-    Vue.component(VueAliplayerV2.name, VueAliplayerV2);
-};
-VueAliplayerV2.Player = VueAliplayerV2;
-export default VueAliplayerV2;
--- a/packages/index.ts
+++ b/packages/index.ts
@ -0,0 +1,112 @@
+import type { App } from 'vue';
+import VueAliplayerV2 from './AliplayerV2/index.vue';
+import { DEFAULT_CSS_LINK, DEFAULT_SCRIPT_SRC, DEFAULT_SDK_VERSION } from './AliplayerV2/sdkLoader';
+import type { VueAliplayerV2Options } from './AliplayerV2/types';
+
+/**
+ * 对外重新导出组件相关类型。
+ *
+ * 使用方可以直接从包入口导入类型，不需要关心内部目录结构。
+ */
+export type {
+    AliplayerEventName,
+    AliplayerInstance,
+    AliplayerLicense,
+    AliplayerOptions,
+    AliplayerV2Props,
+    VueAliplayerV2Expose,
+    VueAliplayerV2Options
+} from './AliplayerV2/types';
+
+/**
+ * 带 Vue 插件安装能力的组件类型。
+ *
+ * Vue SFC 默认导出的类型不包含运行时追加的 `install`、`Player` 和 props 默认值修改能力，
+ * 因此在入口处扩展该类型，保证后续赋值过程在 TypeScript 下可描述。
+ */
+type InstallableVueAliplayerV2 = typeof VueAliplayerV2 & {
+    /**
+     * Vue 插件安装方法，支持 `app.use(VueAliplayerV2, options)`。
+     */
+    install: (app: App, options?: VueAliplayerV2Options) => void;
+    /**
+     * 兼容旧版本 `VueAliplayerV2.Player` 的局部注册写法。
+     */
+    Player: typeof VueAliplayerV2;
+    /**
+     * 组件 props 运行时定义。
+     *
+     * 这里仅列出入口需要改写默认值的 props。
+     */
+    props: {
+        sdkVersion: { default: string | (() => string) };
+        cssLink: { default: string | (() => string) };
+        scriptSrc: { default: string | (() => string) };
+        componentScripts: { default: string[] | (() => string[]) };
+        disableTracking: { default: boolean | (() => boolean) };
+        trackingUrlPatterns: { default: Array<string | RegExp> | (() => Array<string | RegExp>) };
+    };
+};
+
+/**
+ * 全局默认配置。
+ *
+ * 组件 props 的 default 会读取该对象，因此 `app.use` 中传入的配置会影响后续所有未显式
+ * 覆盖同名 props 的播放器实例。
+ */
+const globalOptions: Required<VueAliplayerV2Options> = {
+    sdkVersion: DEFAULT_SDK_VERSION,
+    cssLink: DEFAULT_CSS_LINK,
+    scriptSrc: DEFAULT_SCRIPT_SRC,
+    componentScripts: [],
+    disableTracking: false,
+    trackingUrlPatterns: []
+};
+
+/**
+ * 添加插件安装能力后的播放器组件。
+ */
+const installable = VueAliplayerV2 as unknown as InstallableVueAliplayerV2;
+
+/**
+ * Vue 插件安装入口。
+ *
+ * @param app Vue 应用实例。
+ * @param options 全局默认配置，会合并到 `globalOptions`。
+ */
+installable.install = (app: App, options?: VueAliplayerV2Options): void => {
+    Object.assign(globalOptions, options || {});
+    app.component('VueAliplayerV2', installable);
+};
+
+/**
+ * 从全局配置读取默认 CSS 地址。
+ */
+installable.props.cssLink.default = (): string => globalOptions.cssLink;
+/**
+ * 从全局配置读取默认 JS 地址。
+ */
+installable.props.scriptSrc.default = (): string => globalOptions.scriptSrc;
+/**
+ * 从全局配置读取默认 SDK 版本。
+ */
+installable.props.sdkVersion.default = (): string => globalOptions.sdkVersion;
+/**
+ * 从全局配置读取默认扩展脚本。
+ */
+installable.props.componentScripts.default = (): string[] => globalOptions.componentScripts;
+/**
+ * 从全局配置读取默认统计拦截开关。
+ */
+installable.props.disableTracking.default = (): boolean => globalOptions.disableTracking;
+/**
+ * 从全局配置读取默认统计拦截规则。
+ */
+installable.props.trackingUrlPatterns.default = (): Array<string | RegExp> => globalOptions.trackingUrlPatterns;
+/**
+ * 兼容旧版本的 `VueAliplayerV2.Player` 导出。
+ */
+installable.Player = installable;
+
+export { installable as VueAliplayerV2 };
+export default installable;
--- a/postcss.config.js
+++ b/postcss.config.js
@ -1,5 +0,0 @@
-module.exports = {
-  plugins: {
-    autoprefixer: {}
-  }
-}
--- a/public/index.html
+++ b/public/index.html
@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta http-equiv="X-UA-Compatible" content="IE=edge">
-    <meta name="viewport" content="width=device-width,initial-scale=1.0">
-    <link rel="icon" href="<%= BASE_URL %>favicon.ico">
-    <title>vue-aliplayer-v2</title>
-  </head>
-  <body>
-    <noscript>
-      <strong>We're sorry but vue-aliplayer-v2 doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
-    </noscript>
-    <div id="app"></div>
-    <!-- built files will be auto injected -->
-  </body>
-</html>
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@ -0,0 +1,5 @@
+{
+    "extends": "./tsconfig.json",
+    "include": ["packages/**/*.ts", "packages/**/*.vue", "env.d.ts"],
+    "exclude": ["examples/**", "dist/**", "lib/**", "node_modules/**"]
+}
--- a/tsconfig.json
+++ b/tsconfig.json
@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "useDefineForClassFields": true,
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "strict": true,
+        "jsx": "preserve",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "esModuleInterop": true,
+        "lib": ["ES2022", "DOM", "DOM.Iterable"],
+        "skipLibCheck": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "types": ["node"]
+    },
+    "include": [
+        "env.d.ts",
+        "examples/**/*.ts",
+        "examples/**/*.vue",
+        "packages/**/*.ts",
+        "packages/**/*.vue",
+        "vite.config.ts"
+    ]
+}
--- a/vite.config.ts
+++ b/vite.config.ts
@ -0,0 +1,67 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+/**
+ * Vite 构建配置。
+ *
+ * 项目同时承担两个产物：
+ *
+ * - demo：输出到 `dist`，用于 GitHub Pages 预览。
+ * - lib：输出到 `lib`，用于 npm 包发布。
+ *
+ * 通过 `--mode demo` 区分站点构建，其余模式默认走库构建，避免 demo 资源混入库包。
+ */
+export default defineConfig(({ mode }) => {
+    /**
+     * 是否正在构建 GitHub Pages demo。
+     */
+    const isDemoBuild = mode === 'demo';
+
+    return {
+        /**
+         * GitHub Pages 部署在仓库子路径下，库构建和本地开发使用根路径。
+         */
+        base: isDemoBuild ? '/vue-aliplayer-v2/' : '/',
+        plugins: [vue()],
+        /**
+         * 只有 demo 需要复制 `public` 资源；库构建禁用 publicDir，减少发布产物噪音。
+         */
+        publicDir: isDemoBuild ? 'public' : false,
+        build: isDemoBuild
+            ? {
+                /**
+                 * demo 站点输出目录。
+                 */
+                outDir: 'dist',
+                emptyOutDir: true
+            }
+            : {
+                /**
+                 * npm 包输出目录。
+                 */
+                outDir: 'lib',
+                emptyOutDir: false,
+                /**
+                 * Vue 组件库入口配置。
+                 */
+                lib: {
+                    entry: resolve(__dirname, 'packages/index.ts'),
+                    name: 'VueAliplayerV2',
+                    fileName: 'vue-aliplayer-v2'
+                },
+                /**
+                 * Vue 由宿主项目提供，库包不把 Vue 打进 bundle。
+                 */
+                rollupOptions: {
+                    external: ['vue'],
+                    output: {
+                        exports: 'named',
+                        globals: {
+                            vue: 'Vue'
+                        }
+                    }
+                }
+            }
+    };
+});
--- a/vue.config.js
+++ b/vue.config.js
@ -1,15 +0,0 @@
-// vue.config.js
-module.exports = {
-    // 将 examples 目录添加为新的页面
-    pages: {
-        index: {
-          // page 的入口
-          entry: 'examples/main.js',
-          // 模板来源
-          template: 'public/index.html',
-          // 输出文件名
-          filename: 'index.html'
-        }
-	},
-	publicPath: process.env.NODE_ENV === "production" ? "/vue-aliplayer-v2" : "/"
-}
				`@ -1 +0,0 @@`
				[data-v-9b14a31e]{margin:0;padding:0}.remove-text[data-v-9b14a31e]{text-align:center;padding:20px;font-size:24px}.player-btns[data-v-9b14a31e]{width:100%;display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-pack:justify;-ms-flex-pack:justify;justify-content:space-between;-ms-flex-wrap:wrap;flex-wrap:wrap}.player-btns span[data-v-9b14a31e]{margin:0 auto;display:inline-block;padding:5px 10px;width:150px;height:40px;line-height:40px;border:1px solid #eee;background:#e1e1e1;border-radius:10px;text-align:center;margin:20px auto;cursor:pointer}