Docker容器内存Swap限制需联合设置--memory和--memory-swap，后者为内存与swap总和，实际可用swap等于--memory-swap减--memory；单独设--memory-swap无效，且swap值不得小于memory值。

在 Docker 中配置容器内存 Swap 限制，关键不是单独设 swap，而是通过 memory + memory.swap 联合控制——swap 值必须 ≥ 内存限制值，且实际可交换内存 = memory.swap − memory。直接只设 --memory-swap 不设 --memory 是无效的。

理解 memory 和 memory.swap 的关系

Docker 使用 Linux cgroups v1（默认）时，--memory（即 memory.limit_in_bytes）限制**物理内存使用上限**；--memory-swap（即 memory.memsw.limit_in_bytes）限制**内存 + swap 的总和**。两者必须同时指定，且 swap 值不能小于 memory 值。

• --memory=512m --memory-swap=1g → 最多用 512MB 物理内存 + 最多 512MB swap
• --memory=512m --memory-swap=512m → 禁用 swap（swap 预留为 0）
• --memory=512m --memory-swap=-1 → 允许无限 swap（但物理内存仍限 512MB）
• --memory-swap=1g 单独使用 → 报错：必须同时指定 --memory

运行时配置 swap 限制的正确命令

启动容器时用 docker run 显式传参，确保宿主机已启用 swap 分区（swapon --show 可确认）：

docker run -d \
  --name myapp \
  --memory=256m \
  --memory-swap=768m \
  nginx:alpine

该容器最多使用 256MB 物理内存，超出部分可换出至最多 512MB swap（768 − 256 = 512）。

• 若宿主机无 swap，--memory-swap 大于 --memory 会静默降级为禁用 swap
• cgroups v2 模式下行为略有不同（需启用 systemd.unified_cgroup_hierarchy=1），但 Docker 默认仍走 v1 兼容路径

验证容器 swap 使用是否生效

进容器或查宿主机 cgroup 文件，确认限制已写入：

• 查容器内：cat /sys/fs/cgroup/memory/memory.limit_in_bytes（应为 268435456 = 256MB）
• 查容器内：cat /sys/fs/cgroup/memory/memory.memsw.limit_in_bytes（应为 805306368 = 768MB）
• 查运行中容器实际 swap 使用：docker stats myapp --no-stream 列中的 MEM USAGE / LIMIT 后括号里会显示 swap 用量（如 124.5MiB / 768MiB）

注意：docker stats 显示的 “LIMIT” 是 memory + swap 总和，不是纯物理内存上限。

常见误区与避坑提醒

很多问题源于对参数逻辑的误解：

• 误以为 --memory-swap 单独设置 swap 大小 → 实际它定义的是“内存+swap”总额，减去 --memory 才是可用 swap
• 在无 swap 的宿主机上设大 --memory-swap → 容器无法真正换出，OOM 时仍会直接被 kill，而非利用 swap 缓冲
• 用 docker update 动态调高 --memory-swap 但没同步调高 --memory → 命令会拒绝执行（swap 不能低于当前 memory 值）
• Kubernetes 中对应字段是 memory.limit 和 memory.swap（需 kubelet v1.22+ 且开启 MemorySwap feature gate） → 普通 Docker 场景不涉及