安装包

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", /* ... */ ]
  // ...
}

在某些情况下，您可能在导入时无法获得远程视频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' }
  }
});

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

提供商功能集

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

Amazon S3所需权限

{
  "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-*"
    }
  ]
}

路线图

v0

• 自动视频优化
• 通过CDN交付
• 自动上传和处理本地源文件
• 自动处理远程托管的源文件

v1

• 可自定义播放器
• 连接其他视频服务的连接器
• AI字幕

本地试用

如果您想在本地开发这个项目，您可以克隆并链接它。但请注意...目前还不是很完善。

1. 克隆此仓库
2. cd进入仓库
3. npm install && npm run build
4. cd ../（或返回到您想创建测试应用的位置）
5. npx create-next-app
6. cd your-next-app
7. npx link ../next-video（或您克隆此仓库的位置）