PlaceholderAPI 插件介绍

PlaceholderAPI 插件介绍
概述

PlaceholderAPI（简称 PAPI）是一款面向 Minecraft Java 版 Spigot 系服务端的动态占位符引擎插件，由 HelpChat 组织维护。它本身不直接"输出"任何信息，而是作为一套统一的格式化标准，让聊天、计分板、Tab 列表、菜单、全息图等插件都能以 %标识符_参数% 的形式读取来自其他插件的动态数据——玩家名、余额、权限组前缀、服务器 TPS、在线人数等皆可如此呈现。

截至当前，PlaceholderAPI 在 Spigot 累计下载已超过 200 万次，同时在线服务器超过 5 万台，是各类规模服务器几乎必备的基础设施型插件。
插件名称：PlaceholderAPI（PAPI）
维护者：HelpChat Organization
最新版本：2.12.2（Release）
许可协议：GPL-3.0-only
官方站点：https://placeholderapi.com
项目地址：
Modrinth：https://modrinth.com/plugin/placeholderapi
SpigotMC：https://www.spigotmc.org/resources/placeholderapi.6245
Hangar：https://hangar.papermc.io/HelpChat/PlaceholderAPI
GitHub：https://github.com/PlaceholderAPI/PlaceholderAPI
兼容性

| 项目 | 说明 |
|---|---|
| 游戏版本 | Minecraft Java Edition 1.8.x – 26.1.x |
| 服务端平台 | Bukkit、Spigot、Paper、Folia |
| 前置依赖 | Java 8+（高版本插件需更高 Java） |

> PAPI 2.12.2 起引入了对 Adventure Components 的解析支持，该特性仅在 Paper 及其衍生核心上可用；Spigot 服务端启动时会跳过此类的加载。
核心特性
统一占位符引擎
PAPI 本身不提供任何占位符，所有数据都由"扩展（Expansion）"提供。它负责在字符串中识别 %xxx_yyy% 标记并将其替换为真实数值，让所有消费方插件共享同一套语法。
丰富的扩展生态
通过 PAPI Expansion Cloud（eCloud），服务器管理员可以直接在游戏内下载扩展，目前已超过 230+ 个扩展，覆盖 Essentials、Factions、LuckPerms、Vault 等主流插件。常见的 Player、Server、Bungee、Vault、LuckPerms 等扩展可以满足绝大部分日常需求。
安全与验证机制
从 2.12.2 版本开始，PAPI 会在启动和重载时校验已下载扩展的哈希值，若命中已知恶意扩展名单将强制停止服务器并记录日志；eCloud 也实现了按版本独立验证，只允许下载已验证的扩展版本，从源头降低恶意代码风险。
关系型占位符
支持以 %rel_ 为前缀的关系型占位符，可针对两名玩家进行比较计算（如互相之间的距离、相对排名等），为 Scoreboard、Tab 等插件提供个性化展示能力。
开发者友好 API
插件开发者可通过 PAPI 的 API 轻松注册自定义扩展，将自家插件的数据暴露为占位符供其他插件消费；PAPI 也提供了 PAPIComponents 类等工具简化 Adventure 组件树中的占位符替换。
跨插件通用语言
由于采用统一的占位符格式，聊天插件、计分板插件、Tab 插件、菜单插件、全息图插件等都可以直接读取同一套语法，无需各自实现数据获取逻辑——这是 PAPI 被称为"服务器必备"的根本原因。
安装方法
从 Modrinth / SpigotMC / Hangar 下载 PlaceholderAPI-2.12.2.jar。
将 jar 文件放入服务端的 plugins/ 目录。
启动或重启服务器，PAPI 会自动生成配置文件与 expansions/ 目录。
在游戏内或通过控制台执行 /papi ecloud download <扩展名> 下载所需扩展（如 player、server、vault、luckperms）。
下载完成后执行 /papi reload 重载插件使扩展生效。

> 注意：若服务器所在网络环境无法访问 eCloud（api.extendedclip.com / .placeholderapi.com），可手动从 https://ecloud.placeholderapi.com 下载扩展 jar 并放入 plugins/PlaceholderAPI/expansions/ 目录。
适用场景
任何需要使用动态数据展示的 Spigot / Paper 系服务器
搭配聊天插件（如 ChatLimiter 等）实现个性化变量展示
搭配 Tab 插件、计分板插件、BossBar 插件呈现玩家信息与服务器状态
搭配菜单插件（如 KaMenu）实现数据驱动的对话交互
搭配领地、签到、家园等插件在服务端各类界面中统一显示玩家数据
相关链接
官方网站：https://placeholderapi.com
Modrinth 项目页：https://modrinth.com/plugin/placeholderapi
SpigotMC 资源页：https://www.spigotmc.org/resources/placeholderapi.6245
Hangar 项目页：https://hangar.papermc.io/HelpChat/PlaceholderAPI
GitHub 源码：https://github.com/PlaceholderAPI/PlaceholderAPI
官方 Wiki：https://wiki.placeholderapi.com
eCloud 扩展云：https://ecloud.placeholderapi.com
持续集成构建：https://ci.extendedclip.com/job/PlaceholderAPI/