`next-video`

Next video是一个React组件，用于在您的next.js应用程序中添加视频。它扩展了<video>元素和您的Next应用，提供自动视频优化功能。

智能存储: 将大型视频文件存储在git仓库之外
自动优化: 优化视频文件并通过CDN传输，以获得更好的播放性能和质量
可定制UI: 选择主题或构建自己的播放器控件
海报和预览: 零配置占位图像和时间轴悬停缩略图
更广泛的兼容性: 使用不被所有浏览器原生支持的视频
内置分析（可选）: 查看视频观看频率并跟踪视频性能
AI驱动: 为视频添加自动生成的字幕并使用转录

import Video from 'next-video';
import getStarted from '/videos/get-started.mp4';

export default function Page() {
  return <Video src={getStarted} />;
}

设置

自动设置

在Next.js项目的根目录下运行：

npx -y next-video init

这将（经过提示后）：

安装next-video作为依赖项
更新您的next.config.js文件
如果您使用TypeScript，为视频文件导入添加类型
在您的项目中创建一个/videos目录，用于存放所有视频源文件。

它还会更新您的.gitignore文件，以忽略/videos目录中的视频文件。视频，特别是任何合理大小的视频，不应由git存储/跟踪。或者，如果您想存储原始文件，可以删除添加的gitignore行并安装git-lfs。

远程存储和优化

Vercel建议使用专用的内容平台来处理视频，因为视频文件很大，可能导致过多的带宽使用。默认情况下，next-video使用Mux，它由Video.js的创建者开发，为Patreon等流行的流媒体应用提供支持，其视频性能监控用于世界上最大的直播活动。

注册Mux
创建访问令牌
将环境变量添加到.env.local（或您导出本地环境变量的方式）

# .env.local
MUX_TOKEN_ID=[YOUR_TOKEN_ID]
MUX_TOKEN_SECRET=[YOUR_TOKEN_SECRET]

手动设置

<details> <summary><strong>点击查看手动初始化步骤。</strong></summary>

安装包

cd your-next-app

# 如果您的项目使用NPM（Next.js的默认设置）
npm install next-video

# 如果您的项目使用Yarn
yarn add next-video

# 如果您的项目使用pnpm
pnpm add next-video

将Next Video添加到`next.config.js`

/** @type {import('next').NextConfig} */
const { withNextVideo } = require('next-video/process');

const nextConfig = {}; // 您当前的Next配置对象

module.exports = withNextVideo(nextConfig);

将视频导入类型添加到`tsconfig.json`

这仅在您使用TypeScript时需要，确保您的视频文件导入不会因缺少类型而报错。当您运行npx next-video init时，video.d.ts应该已在您的项目根目录中创建，如果没有，您可以手动创建：

// video.d.ts
/// <reference types="next-video/video-types/global" />

然后将该文件添加到tsconfig.json的include数组中。

{
  // ...
  "include": ["video.d.ts", "next-env.d.ts", /* ... */ ]
  // ...
}

</details>

使用方法

本地视频（演示）

将视频添加到/videos目录，然后运行npx next-video sync。视频将自动上传到远程存储并进行优化。您会注意到/videos/[file-name].json文件也被创建。这些文件用于将本地视频文件映射到新的远程托管视频资源。这些json文件必须提交到git。

npx next-video sync

您还可以将next-video sync -w添加到dev脚本中，以在开发服务器运行时自动同步添加到/videos的视频。

// package.json
"scripts": {
  "dev": "next dev & npx next-video sync -w",
},

现在您可以在应用程序中使用<Video>组件。假设您已经将一个名为awesome-video.mp4的文件添加到了/videos

import Video from 'next-video';
import awesomeVideo from '/videos/awesome-video.mp4';

export default function Page() {
  return <Video src={awesomeVideo} />;
}

当视频正在上传和处理时，<Video>将尝试播放本地文件。这只发生在本地开发期间，因为本地文件从不上传到您的git仓库。

远程视频

对于已经远程托管的视频（例如在AWS S3上），导入远程URL并刷新页面。这会在/videos文件夹中创建一个本地JSON文件，同步脚本将开始上传视频。

import Video from 'next-video';
import awesomeVideo from 'https://www.mydomain.com/remote-video.mp4';

export default function Page() {
  return <Video src={awesomeVideo} />;
}

如果托管的视频是单个文件，如MP4，该文件将自动优化以提高可交付性和兼容性。

<details> <summary><strong>使用字符串源URL的远程视频</strong></summary>

在某些情况下，您可能在导入时无法获得远程视频URL。这可以通过在 Next.js 应用中为 /api/video 创建一个新的 API 端点来解决，代码如下：

App 路由 (Next.js >=13)

// app/api/video/route.js
export { GET } from 'next-video/request-handler';

Pages 路由 (Next.js)

// pages/api/video/[[...handler]].js
export { default } from 'next-video/request-handler';

然后将 src 属性设置为远程视频的 URL，刷新页面，视频就会开始处理。

import Video from 'next-video';

export default function Page() {
  return <Video src="https://www.mydomain.com/remote-video.mp4" />;
}

仅播放器 (演示)

从 v1.1.0 版本开始，你可以直接导入播放器组件，并在不需要上传和处理功能的情况下使用它。

import Player from 'next-video/player';
// 或
import BackgroundPlayer from 'next-video/background-player';

export default function Page() {
  return <Player
    src="https://www.mydomain.com/remote-video.mp4"
    poster="https://www.mydomain.com/remote-poster.webp"
    blurDataURL="data:image/webp;base64,UklGRlA..."
  />;
}

自定义海报和模糊数据 URL

你可以通过传递属性来为视频添加自定义海报和模糊数据 URL。

import Video from 'next-video';
import awesomeVideo from '/videos/awesome-video.mp4';
import awesomePoster from '../public/images/awesome-poster.jpg';

export default function Page() {
  return <Video 
    src={awesomeVideo} 
    poster={awesomePoster.src} 
    blurDataURL={awesomePoster.blurDataURL} 
  />;
}

这是一个不错的解决方案，但它无法提供与默认提供者自动生成的海报和模糊数据 URL 相同级别的优化。

要获得相同级别的优化，你可以使用插槽海报元素。

插槽海报图像元素 (演示)

通过传递带有 slot="poster" 属性的子元素，为视频添加插槽海报图像元素（如 next/image）。

现在你的图像将获得所使用的图像组件的所有优势，并且会被漂亮地放置在视频播放器控件后面。

import Image from 'next/image';
import Video from 'next-video';
import awesomeVideo from '/videos/awesome-video.mp4';
import awesomePoster from '../public/images/awesome-poster.jpg';

export default function Page() {
  return (
    <Video src={awesomeVideo}>
      <Image 
        slot="poster" 
        src={awesomePoster}
        placeholder="blur"
        alt="一些人在做令人惊叹的事情"
      />
    </Video>
  );
}

自定义播放器 (演示)

你可以通过将自定义播放器组件传递给 as 属性来自定义播放器。自定义播放器组件接受以下属性：

asset：处理后的资源，包含有用的资源元数据和上传状态。
src：如果资源已就绪，则为字符串视频源 URL。
poster：如果资源已就绪，则为字符串图像源 URL。
blurDataURL：可用作占位符的字符串 base64 图像源 URL。

import Video from 'next-video';
import ReactPlayer from './player';
import awesomeVideo from '/videos/awesome-video.mp4';

export default function Page() {
  return <Video as={ReactPlayer} src={awesomeVideo} />;
}

// player.tsx
'use client';

import type { PlayerProps } from 'next-video';
import ReactPlayer from 'react-player';

export default function Player(props: PlayerProps) {
  let { asset, src, poster, blurDataURL, thumbnailTime, ...rest } = props;
  let config = { file: { attributes: { poster } } };

  return <ReactPlayer
    url={src}
    config={config}
    width="100%"
    height="100%"
    {...rest}
  />;
}

背景视频 (演示)

你可以使用 <BackgroundVideo> 组件来添加一个没有播放器控件的背景视频。这可以节省约 50% 的 JS 播放器大小，并针对背景视频使用进行了优化。

<BackgroundVideo> 组件是一个自定义播放器，就像你在前一节中看到的那样。

下面示例中的 thumbnailTime 查询参数用于在视频的指定时间生成海报图像和模糊图像（仅限于使用 mux 提供者）。

import BackgroundVideo from 'next-video/background-video';
import getStarted from '/videos/country-clouds.mp4?thumbnailTime=0';

export default function Page() {
  return (
    <BackgroundVideo src={getStarted}>
      <h1>next-video</h1>
      <p>
        一个用于在 Next.js 应用中添加视频的 React 组件。
        它扩展了视频元素和你的 Next 应用，提供了自动视频优化的功能。
      </p>
    </BackgroundVideo>
  );
}

托管和处理提供者

你可以在不同的提供者之间选择视频处理和托管服务。默认提供者是 Mux。要更改提供者，你可以在 next-video 配置中添加 provider 选项。某些提供者需要额外的配置，可以通过 providerConfig 属性传递。

// next.config.js
const { withNextVideo } = require('next-video/process');

/** @type {import('next').NextConfig} */
const nextConfig = {};

module.exports = withNextVideo(nextConfig, {
  provider: 'backblaze',
  providerConfig: {
    backblaze: { endpoint: 'https://s3.us-west-000.backblazeb2.com' }
  }
});

支持的提供者及其所需的环境变量：

提供商	环境变量	提供商配置	价格链接
`mux`（默认）	`MUX_TOKEN_ID`<br/>`MUX_TOKEN_SECRET`		价格
`vercel-blob`	`BLOB_READ_WRITE_TOKEN`		价格
`backblaze`	`BACKBLAZE_ACCESS_KEY_ID`<br/>`BACKBLAZE_SECRET_ACCESS_KEY`	`endpoint`<br/>`bucket`（可选）	价格
`amazon-s3`	`AWS_ACCESS_KEY_ID`<br/>`AWS_SECRET_ACCESS_KEY`	`endpoint`<br/>`bucket`（可选）	价格

提供商功能集

	Mux（默认）	Vercel Blob	Backblaze	Amazon S3
非仓库存储	✅	✅	✅	✅
通过CDN交付	✅	✅	-	-
自带播放器	✅	✅	✅	✅
压缩以便流式传输	✅	-	-	-
适应慢速网络（HLS）	✅	-	-	-
自动生成占位海报	✅	-	-	-
时间轴悬停缩略图	✅	-	-	-
流式传输任何源格式	✅	*	*	*
AI字幕和字幕	✅	-	-	-
视频分析	✅	-	-	-
定价	基于分钟	基于GB	基于GB	基于GB

*对于没有视频处理功能的托管提供商，需要提供兼容Web的MP4文件

Amazon S3所需权限

<details> <summary>如果您使用Amazon S3作为提供商，您需要创建一个具有以下权限的新IAM用户：</summary>

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:CreateBucket",
        "s3:PutBucketOwnershipControls"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutBucketPublicAccessBlock",
        "s3:PutBucketAcl",
        "s3:PutBucketCORS",
        "s3:GetObject",
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::next-videos-*"
    }
  ]
}