强曰为道

与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

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-distancesimulation-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.propertiesview-distance6-12(根据人数调整)
server.propertiessimulation-distance≤ view-distance
server.propertiesonline-modetrue(生产环境)
paper-global.ymlentity-collisionsfalse(公共服)
paper-world-defaults.ymlentity-activation-range32(动物/怪物)
bukkit.ymlspawn-limits.monsters50-70
spigot.ymlentity-activation-range与 paper 配置一致

扩展阅读