前言

对于拥有 Alist 服务的博客主来说，如何将存储的影视资源优雅地展示在自己的 Hexo 博客上是一个常见需求。手动整理信息不仅费时费力，而且难以维护。hexo-alist-movie-plugin 是一个旨在解决此问题的强大插件，它能连接到 Alist 服务器，通过内置的智能识别引擎自动扫描和分析影视资源，并结合 TMDb API 为网站生成包含丰富元数据、设计精美的电影和电视剧展示页面。

本文将详细介绍该插件的特性、安装配置与使用方法。

方案特点

智能识别引擎：无需手动分类，插件能自动分析混合内容的目录，智能区分电影和电视剧，并从复杂文件名中提取季号和集数。
精准信息匹配：支持在文件名或目录名中使用 TMDb ID（如 电影名称 (12345)），实现 100% 准确的信息匹配。
内容自动聚合：自动将同一影视内容的不同版本（如 4K、1080p）聚合为单个条目，并在播放页提供版本选择。
元数据丰富：自动从 TMDb 获取海报、简介、演员、评分、流派等海量信息。
现代化前端：提供响应式设计的瀑布流列表页，支持即时筛选和排序；播放器页面则基于 Plyr.js 构建。
诊断工具：内置文件识别对比工具，帮助用户诊断和优化文件命名。
配置灵活：支持配置多个 Alist 目录，可分别指定为电影、电视剧或交由智能引擎处理的混合内容。
稳定健壮：内置 API 请求重试与缓存机制，保证网站生成过程的稳定性。

准备工作

一个正常运行的 Hexo 博客。
Alist 服务器的访问凭证（URL、用户名、密码）。
TMDb API v3 Auth Token（可免费申请）。

基础使用

1. 安装插件

在 Hexo 博客根目录下执行以下命令：

npm install hexo-alist-movie-plugin

2. 配置插件

在 Hexo 根目录下的 _config.yml 文件中，添加以下配置项并根据你的实际情况修改：

# Alist 影视库生成器配置
alist_movie_generator:
  # Alist 服务器信息 (必填)
  alist:
    url: "https://your-alist-url.com"      # 你的 Alist 服务器地址
    username: "your-alist-username"    # Alist 用户名
    password: "your-alist-password"    # Alist 密码

  # TMDb API v3 Auth Token (必填)
  tmdb_token: "your-tmdb-api-v3-auth-token"

  # --- 目录配置 ---
  # 电影目录：明确指定这些目录下的内容为电影
  movies:
    - path: "/movies/action"

  # 电视剧目录：明确指定这些目录下的内容为电视剧
  tv_shows:
    - path: "/tv/us"

  # 混合内容目录 (最强大的功能):
  # 插件将自动分析此目录下的内容，智能区分电影和电视剧
  mixed_content:
    - path: "/mixed_media"

  # 输出配置 (可选)
  output:
    route: "movies"              # 生成页面的路由 (即 yoursite.com/movies/)
    per_page: 24                 # 列表页每页显示的项目数量
    order_by: "rating"           # 默认排序字段 (rating, popularity, date, title)
    order: "desc"                # 默认排序方向 (asc, desc)

mixed_content 是本插件的核心功能，即使文件未分类，它也能尽力识别出正确的内容。

3. 生成数据与页面

插件的工作流程分为两步：获取数据 和 生成页面。

更新影视数据: 运行以下命令来从 Alist 和 TMDb 获取最新的影视信息。此命令会生成一个 source/data/movies.json 文件。
```
hexo alist_movie -u
```
生成网站页面: 数据更新后，像往常一样生成或预览您的网站即可。
```
# 生成静态文件
hexo g

# 或者启动本地预览
hexo s
```

进阶使用

命名与目录结构最佳实践

为了获得最高的识别准确率，强烈推荐采用以下目录结构和命名规范。

/Alist根目录
├── 电影 (movies)
│   ├── 阿凡达 (2009)
│   │   └── Avatar.2009.1080p.mkv
│   └── 你的名字 (372058)  <-- 最佳实践！使用 TMDb ID
│       └── Your.Name.2016.2160p.mkv
└── 电视剧 (tv_shows)
    ├── 权力的游戏
    │   └── Season 01
    │       └── Game.of.Thrones.S01E01.mkv
    └── 间谍过家家 (120089)   <-- 最佳实践！使用 TMDb ID
        └── S01
            └── spy.family.s01e01.mkv

核心技巧：

为每个影视内容创建独立文件夹。
在文件夹名称中包含年份，例如 电影名称 (2023)。
电视剧按季分文件夹，例如 Season 01 或 S01。
【强烈推荐】使用 TMDb ID：在文件夹或文件名中添加 (TMDb ID)，例如 (372058)。插件会优先使用此 ID 进行匹配，准确率 100%。

文件识别对比工具

插件会自动生成一个对比页面，帮助你检查识别效果。访问 http://yoursite.com/movies/comparison.html (或您自定义的路由)，您可以看到原始文件名与识别结果的对应关系，便于调整和优化文件命名。

命令行工具

本插件提供了一个独立的命令行工具来管理影视数据，使数据更新与网站生成解耦。

更新/生成数据
连接 Alist 和 TMDb，创建或更新 source/data/movies.json 文件。
```
hexo alist_movie -u
# 或
hexo alist_movie --update
```
删除数据
删除 source/data/movies.json 文件。删除后，hexo g 将不会生成任何影视页面。
```
hexo alist_movie -d
# 或
hexo alist_movie --delete
```
提示: 删除数据文件后，建议运行 hexo clean 来清理旧的已生成的 HTML 文件。

常见问题

TMDb API 连接失败或超时怎么办？
插件内置了重试机制。请检查服务器网络是否能正常访问 api.themoviedb.org。如果在中国大陆服务器上运行，可能需要配置代理。
有些影片识别不正确怎么办？
首先，访问文件识别对比工具页面，查看具体的匹配情况。最佳解决方案是使用 TMDb ID 命名法。其次，可以尝试优化文件夹和文件名，使其更规范。
可以自定义播放器页面的样式吗？
可以。您可以直接修改插件目录下的 source/player/style.css 文件，或者在您的 Hexo 主题中通过 CSS 覆盖其样式。
支持 Openlist 吗？
支持。Alist 和 Openlist 的 API 是一样的，因此本插件同样适用于 Openlist。