Minecraft PaperMC 服务器部署指南 / 03 - 核心配置详解
03 - 核心配置详解
3.1 配置文件总览
PaperMC 的配置分为三层:
| 配置文件 | 作用域 | 说明 |
|---|---|---|
server.properties | 全局 | Mojang 原版配置,端口、白名单、游戏规则等 |
config/paper-global.yml | 全局 | Paper 特有的全局设置,性能、日志、行为等 |
config/paper-world-defaults.yml | 每世界默认 | 世界级别的设置默认值 |
config/paper-world-<世界名>.yml | 特定世界 | 覆盖特定世界的设置 |
配置优先级:paper-world-<世界名>.yml > paper-world-defaults.yml > paper-global.yml > server.properties
3.2 server.properties 详解
3.2.1 网络与连接
# 服务器监听端口
server-port=25565
# 服务器监听地址(留空监听所有接口)
server-ip=
# 最大玩家数
max-players=20
# 白名单
white-list=false
# 强制白名单(即使 OP 也需要在白名单中)
enforce-whitelist=false
# 在线模式验证(正版验证,生产环境必须为 true)
online-mode=true
# 防止使用代理 IP(BungeeCord/Velocity 背后设为 false)
prevent-proxy-connections=false
# 玩家空闲超时(分钟,0 表示不踢出)
player-idle-timeout=0
# 网络压缩阈值(字节)
network-compression-threshold=256
# 同时登录的最大数量
rate-limit=0
安全警告:
online-mode除非你在使用代理(BungeeCord/Velocity),否则永远设为 true。设为 false 允许盗版玩家进入,并且存在严重的安全风险。
3.2.2 世界与游戏
# 世界名称(对应 world/ 文件夹名)
level-name=world
# 默认游戏模式:survival/creative/adventure/spectator
gamemode=survival
# 游戏难度:peaceful/easy/normal/hard
difficulty=normal
# 世界种子(留空随机生成)
level-seed=
# 世界类型:minecraft\:normal / minecraft\:flat / minecraft\:large_biomes / custom
level-type=minecraft\:normal
# 生成结构(村庄、要塞等)
generate-structures=true
# 最大建筑高度
max-build-height=256
# 允许下界
allow-nether=true
# 生成保护半径(出生点保护,0 禁用)
spawn-protection=16
# 强制默认游戏模式(玩家切换世界后保持)
force-gamemode=false
# 允许飞行
allow-flight=false
# 最大世界边界半径
max-world-size=29999984
3.2.3 命令与红石
# 启用命令方块
enable-command-block=false
# 控制台命令反馈
broadcast-console-to-ops=true
# 向管理员广播 RCON 消息
broadcast-rcon-to-ops=true
# 启用 RCON(远程控制台)
enable-rcon=false
rcon.port=25575
rcon.password=
# 启用 Query 协议
enable-query=false
query.port=25565
# 启用 JMX 监控
enable-jmx-monitoring=false
3.2.4 视距与性能(重要)
# 视距(Chunk 数,2-32,默认 10)
# 影响客户端渲染和服务器负载
view-distance=10
# 模拟距离(Chunk 数,控制实体和红石运算范围)
simulation-distance=10
# 启用状态回复(减少带宽)
status=true
性能提示:
view-distance和simulation-distance是影响服务器性能最大的两个参数。
- 小型服务器:view=10, simulation=8
- 中型服务器:view=8, simulation=6
- 大型服务器:view=6, simulation=4
3.3 paper-global.yml 详解
该文件在首次启动 PaperMC 后自动生成于 config/paper-global.yml。
3.3.1 性能相关
chunk-loading-advanced:
# 自动配置区块加载线程数(推荐 true)
auto-config-send-distance: true
# 每个玩家的最大待发送区块数
player-max-concurrent-chunk-generates: 0 # 0 = 自动
player-max-concurrent-chunk-loads: 0 # 0 = 自动
chunk-system:
# 区块系统线程数(0 = CPU 核心数的一半)
gen-parallelism: default
# IO 线程数
io-threads: 2
# worker 线程数
worker-threads: 2
collisions:
# 是否允许实体碰撞(关闭可提升性能)
enable-player-collisions: false
# 发送碰撞包的最小玩家数
send-full-pos-for-hard-colliding-entities: true
misc:
# 最大实体追踪距离(方块数)
max-entity-tracking: default
# 红石时钟频率限制(tick 数,0 不限制)
redstone-implementation: default
tick-rates:
# 每 tick 处理的行为频率
behavior:
villager:
validatenearbypoi: -1 # -1 = 使用默认值
frog:
tempt: 2
sniffer:
default: 20
container-update: 1
dry-farmland: 1
grass-spread: 1
mob-spawner: 1
sensor:
villager:
secondarypoisensor: 80
nearestbedsensor: 80
nearestlivingentitysensor: 40
playersensor: 40
villagerhostelessensor: 200
behavior:
villager:
validatenearbypoi: -1
3.3.2 消息与日志
messages:
# 服务器满员时的踢出信息
kick:
authentication-servers-down: "<lang:multiplayer.disconnect.authservers_down>"
connection-throttle: "连接过于频繁,请稍后再试"
flying-player: "飞行检测未通过"
flying-vehicle: "载具飞行检测未通过"
# 使用动作栏显示坐标(F3+C 替代)
use-display-name-in-quit-message: false
logging:
# 控制台日志级别
deobfuscate-stacktraces: true
# 玩家 IP 记录(隐私考虑可关闭)
log-player-ip-addresses: true
# Log4j 配置
use-rgb-for-named-text-colors: true
3.3.3 代理相关(Velocity/BungeeCord)
proxies:
# 使用代理时必须设为 true
bungee-cord:
online-mode: true
velocity:
enabled: true
online-mode: true
secret: "" # 与 velocity.toml 中的 secret 一致
注意:如果使用 Velocity 代理,需要设置
velocity.enabled: true并配置secret。不要同时启用 BungeeCord 和 Velocity。
3.3.4 命令与功能
commands:
# 命令方块设置
command-block-overrides: []
# 不可丢弃的物品
unconditional-command-block-permission: false
# suggest-player-names-when-null-tab-completions: true
unsupported-settings:
# 允许修复被破坏的方块(如被零刻活塞破坏的方块)
allow-grindstone-overstacking: false
allow-headless-pistons: false
allow-permanent-block-break-exploits: false
allow-piston-duplication: false
# 这些是 Paper 修复的 Vanilla "特性"(漏洞利用)
# 设为 true 可以恢复旧行为,但会带来安全/平衡问题
3.4 paper-world-defaults.yml 详解
世界级别的配置,影响实体生成、方块行为等。
3.4.1 实体生成
entities:
spawning:
# 每 tick 的非生物实体生成上限
non-player-arrow-despawn-rate: 30 # 箭矢消失时间(tick)
creative-arrow-despawn-rate: 30
# 怪物生成上限
monsters:
max-per-chunk: 70 # 每 chunk 最大怪物数
animals:
max-per-chunk: 10
water-animals:
max-per-chunk: 5
water-ambient:
max-per-chunk: 20
water-underground-creature:
max-per-chunk: 5
axolotls:
max-per-chunk: 5
ambient:
max-per-chunk: 15
# 实体激活范围(方块数)
entity-activation-range:
animals: 32
monsters: 32
raiders: 64
misc: 16
water: 16
villagers: 32
flying-monsters: 32
# 远离激活范围的实体是否以降低频率更新
tick-inactive-goals: true
# 不活跃实体的更新频率(tick)
inactive-goal-update-rate: 1
# 实体跟踪
entity-tracking-range:
players: 128
animals: 96
monsters: 96
misc: 64
other: 64
display: 128
# 合并距离(掉落物合并范围)
mob-spawn-range: 4
3.4.2 方块行为
fixes:
# 修复 TNT 拉线重复触发
disable-unloaded-chunk-enderpearl-exploit: true
# 修复刷线机
split-overstacked-loot: true
# 修复 tnt-dupe
prevent-tnt-from-moving-in-water: false
environment:
# 是否允许在下界顶部放置方块(出生点平台)
allow-nether-bed-roof: true
# 恶魂是否只在指定亮度以上生成
nether-ceiling-void-damage-height: 0
scoreboards:
# 允许非实体跟踪记分板
allow-non-player-entities-on-scoreboards: true
hopper:
# 漏斗冷却时间(tick)
cooldown-when-full: true
# 漏斗每 tick 检查的物品数
disable-move-event: false
3.4.3 玩家与连接
player-auto-save-rate: 6000 # 自动保存间隔(tick,5分钟)
max-player-auto-save-per-tick: -1 # 每 tick 最大保存数(-1 = 不限)
anticheat:
# 反作弊设置
anti-xray:
enabled: false
engine-mode: 1 # 1 = 替换矿石,2 = 替换所有方块
hidden-blocks:
- gold_ore
- diamond_ore
- emerald_ore
- ancient_debris
lava-obscures: true
update-radius: 2
use-permission: false
3.5 多世界配置覆盖
当需要为特定世界使用不同于默认值的配置时:
3.5.1 创建特定世界配置
# 假设有一个名为 "creative" 的创造世界
# 复制默认配置作为起点
cp config/paper-world-defaults.yml config/paper-world-creative.yml
3.5.2 修改特定世界配置
# config/paper-world-creative.yml
# 创造模式下不限制实体生成
entities:
spawning:
monsters:
max-per-chunk: 0 # 不生成怪物
animals:
max-per-chunk: 0 # 不生成动物
# 更大的模拟距离(创造模式需要)
chunks:
auto-save-interval: 6000
3.6 bukkit.yml 配置
Bukkit 层配置文件,影响插件兼容性:
# bukkit.yml
settings:
allow-end: true
warn-on-overload: true
permissions-file: permissions.yml
update-folder: update
plugin-profiling: false
connection-throttle: 4000
query-plugins: true
deprecated-verbose: default
shutdown-message: "服务器已关闭"
minimum-api: none
use-map-color-cache: true
spawn-limits:
monsters: 70 # 每世界最大怪物数
animals: 10 # 每世界最大动物数
water-animals: 5
water-ambient: 20
water-underground-creature: 5
axolotls: 5
ambient: 15
chunk-gc:
period-in-ticks: 600 # 垃圾回收无用 chunk 的间隔
ticks-per:
animal-spawns: 400
monster-spawns: 1
water-spawns: 1
water-ambient-spawns: 1
water-underground-creature-spawns: 1
axolotl-spawns: 1
ambient-spawns: 1
autosave: 6000
3.7 spigot.yml 关键配置
# spigot.yml
settings:
save-user-cache-on-stop-only: false
bungeecord: false # 使用 BungeeCord 时设为 true
sample-count: 12
player-shuffle: 0
user-cache-size: 1000
moved-wrongly-threshold: 0.0625
moved-too-quickly-multiplier: 10.0
log-villager-deaths: true
log-named-deaths: true
timeout-time: 60
restart-on-crash: true
restart-script: ./start.sh # 崩溃后自动重启脚本
world-settings:
default:
entity-activation-range:
animals: 32
monsters: 32
raiders: 64
misc: 16
water: 16
villagers: 32
flying-monsters: 32
tick-inactive-goals: true
merge-radius:
exp: 3.0
item: 2.5
item-despawn-rate: 6000
zombie-aggressive-towards-villager: true
3.8 常用配置修改场景
场景一:小型私人服
# server.properties
max-players=10
view-distance=12
simulation-distance=8
difficulty=normal
allow-flight=true
spawn-protection=0
# paper-world-defaults.yml
entities:
spawning:
monsters:
max-per-chunk: 50
场景二:中型公共服(50人)
# server.properties
max-players=50
view-distance=8
simulation-distance=6
white-list=false
# paper-global.yml
chunk-system:
gen-parallelism: default
io-threads: 4
worker-threads: 4
collisions:
enable-player-collisions: false
场景三:创造建筑服
# server.properties
gamemode=creative
allow-flight=true
max-players=30
view-distance=16
simulation-distance=10
spawn-protection=0
3.9 配置热重载
部分配置修改后需要重启服务器才能生效。以下是常见情况:
| 配置文件 | 热重载命令 | 备注 |
|---|---|---|
| server.properties | 无,需重启 | 所有改动需重启 |
| paper-global.yml | 部分项需重启 | 标记为 “requires restart” 的项 |
| paper-world-*.yml | /paper reload | 不推荐,可能导致问题 |
| bukkit.yml | 需重启 | |
| spigot.yml | 需重启 |
最佳实践:修改任何配置文件后,始终重启服务器。使用
/reload或/paper reload可能导致内存泄漏和插件状态异常。
3.10 本章小结
| 配置文件 | 关键项 | 推荐值 |
|---|---|---|
| server.properties | view-distance | 6-12(根据人数调整) |
| server.properties | simulation-distance | ≤ view-distance |
| server.properties | online-mode | true(生产环境) |
| paper-global.yml | entity-collisions | false(公共服) |
| paper-world-defaults.yml | entity-activation-range | 32(动物/怪物) |
| bukkit.yml | spawn-limits.monsters | 50-70 |
| spigot.yml | entity-activation-range | 与 paper 配置一致 |