diff --git a/docs/common/radxa-os/system-config/_swap.mdx b/docs/common/radxa-os/system-config/_swap.mdx
new file mode 100644
index 000000000..4f7cccd39
--- /dev/null
+++ b/docs/common/radxa-os/system-config/_swap.mdx
@@ -0,0 +1,139 @@
+Radxa OS 默认会启用一个大小约为 **物理内存一半** 的 swap 分区，通常已经可以覆盖大部分日常使用场景。
+
+当设备物理内存较小、偶尔会跑较大负载时，可以在此基础上**额外创建 swap 文件**，作为临时扩展和应急缓冲。
+
+下面介绍如何在 Radxa 设备上添加一个简单的 swap 文件。
+
+:::caution 注意
+swap 仅适合作为“兜底”，会降低性能并增加 eMMC/SD/SSD 的写入磨损，不建议长期依赖。
+:::
+
+## 一、什么时候需要 swap？
+
+- 内存较小，偶尔会编译大工程 / 运行占用高的程序
+- 希望在内存突然吃紧时，系统不要直接 OOM 崩溃
+
+如果你追求极致性能或担心闪存寿命，也可以选择完全不启用 swap。
+
+## 二、查看当前内存与 swap 情况
+
+
+
+```
+free -h
+sudo swapon --show
+```
+
+
+
+若 `swapon --show` 无输出，说明当前系统未启用 swap。
+
+## 三、创建并启用 swap 文件（以 2G 为例）
+
+
+
+```
+sudo fallocate -l 2G /swapfile # 创建文件
+sudo chmod 600 /swapfile # 只允许 root 访问
+sudo mkswap /swapfile # 格式化为 swap
+sudo swapon /swapfile # 立即启用
+```
+
+
+
+再次确认：
+
+
+
+```
+swapon --show
+free -h
+```
+
+
+
+## 四、设置开机自动启用 swap
+
+先备份 `fstab`（推荐）：
+
+
+
+```
+sudo cp /etc/fstab /etc/fstab.bak
+```
+
+
+
+编辑 `fstab`：
+
+
+
+```
+sudo vim /etc/fstab
+```
+
+
+
+在文件末尾添加一行：
+
+
+
+```
+/swapfile none swap sw 0 0
+```
+
+
+
+保存退出后，用下面命令测试配置是否正确：
+
+
+
+```
+sudo swapoff /swapfile
+sudo swapon -a
+sudo swapon --show
+```
+
+
+
+能正常看到 `/swapfile`，说明 `fstab` 配置生效且无语法错误。
+
+:::tip
+`swapon -a` 会按照 `/etc/fstab` 中的配置重新启用所有 swap 设备，是检查配置是否正确的安全方法。
+:::
+
+## 五、禁用并删除 swap 文件
+
+若后续不再需要该 swap 文件，可按以下步骤关闭并删除：
+
+1. 关闭 swap：
+
+
+
+```
+ sudo swapoff /swapfile
+```
+
+
+
+2. 编辑 `/etc/fstab`，删除或注释掉下面这一行：
+
+
+
+```
+ /swapfile none swap sw 0 0
+```
+
+
+
+3. 删除文件：
+
+
+
+```
+ sudo rm /swapfile
+```
+
+
+
+完成以上操作后，系统将恢复为无该 swap 文件的状态。
diff --git a/docs/cubie/a5e/system-config/swap.md b/docs/cubie/a5e/system-config/swap.md
new file mode 100644
index 000000000..6285c229e
--- /dev/null
+++ b/docs/cubie/a5e/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# 交换分区与 swap 文件
+
+
diff --git a/docs/cubie/a5e/system-config/system_update.md b/docs/cubie/a5e/system-config/system_update.md
index 3e92fff7a..97d02bf4d 100644
--- a/docs/cubie/a5e/system-config/system_update.md
+++ b/docs/cubie/a5e/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# 系统更新
+:::tip
+
+搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。
+
+:::
+
diff --git a/docs/cubie/a7a/system-config/swap.md b/docs/cubie/a7a/system-config/swap.md
new file mode 100644
index 000000000..6285c229e
--- /dev/null
+++ b/docs/cubie/a7a/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# 交换分区与 swap 文件
+
+
diff --git a/docs/cubie/a7a/system-config/system_update.md b/docs/cubie/a7a/system-config/system_update.md
index cb0742d7c..f814f9adc 100644
--- a/docs/cubie/a7a/system-config/system_update.md
+++ b/docs/cubie/a7a/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# 系统更新
+:::tip
+
+搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。
+
+:::
+
diff --git a/docs/cubie/a7z/system-config/swap.md b/docs/cubie/a7z/system-config/swap.md
new file mode 100644
index 000000000..6285c229e
--- /dev/null
+++ b/docs/cubie/a7z/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# 交换分区与 swap 文件
+
+
diff --git a/docs/cubie/a7z/system-config/system_update.md b/docs/cubie/a7z/system-config/system_update.md
index cb0742d7c..f814f9adc 100644
--- a/docs/cubie/a7z/system-config/system_update.md
+++ b/docs/cubie/a7z/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# 系统更新
+:::tip
+
+搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。
+
+:::
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx
new file mode 100644
index 000000000..d46b0b16e
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx
@@ -0,0 +1,139 @@
+Radxa OS enables a swap **partition** by default, with a size of about **half of the physical memory**, which is usually enough for most daily use cases.
+
+When the device has relatively small RAM and you occasionally run heavy workloads, you can **add an extra swap file** on top of the default swap partition as a temporary extension and safety buffer.
+
+The following describes how to add a simple swap file on a Radxa device.
+
+:::caution Note
+Swap is only a **fallback** mechanism. It will slow down the system and increase write wear on eMMC/SD/SSD. Long‑term reliance on swap is not recommended.
+:::
+
+## 1. When do you need swap?
+
+- RAM is small, and you occasionally compile large projects or run memory‑hungry programs
+- You want to reduce the chance of the system going OOM and crashing when memory usage spikes
+
+If you care about extreme performance or flash lifetime, you can also choose not to enable swap at all.
+
+## 2. Check current memory and swap
+
+
+
+```
+free -h
+sudo swapon --show
+```
+
+
+
+If `swapon --show` prints nothing, it means no swap is currently enabled.
+
+## 3. Create and enable a swap file (2G example)
+
+
+
+```
+sudo fallocate -l 2G /swapfile # create file
+sudo chmod 600 /swapfile # only root can access
+sudo mkswap /swapfile # format as swap
+sudo swapon /swapfile # enable immediately
+```
+
+
+
+Verify:
+
+
+
+```
+swapon --show
+free -h
+```
+
+
+
+## 4. Enable the swap file at boot
+
+First, back up `fstab` (recommended):
+
+
+
+```
+sudo cp /etc/fstab /etc/fstab.bak
+```
+
+
+
+Edit `fstab`:
+
+
+
+```
+sudo vim /etc/fstab
+```
+
+
+
+Add the following line at the end of the file:
+
+
+
+```
+/swapfile none swap sw 0 0
+```
+
+
+
+Save and exit, then test whether the configuration works:
+
+
+
+```
+sudo swapoff /swapfile
+sudo swapon -a
+sudo swapon --show
+```
+
+
+
+If `/swapfile` appears in the output, the `fstab` configuration is valid and has no syntax errors.
+
+:::tip
+`swapon -a` re‑enables all swap devices according to `/etc/fstab`. It is a safe way to verify that your configuration is correct.
+:::
+
+## 5. Disable and remove the swap file
+
+If you no longer need the swap file, follow these steps to disable and remove it:
+
+1. Turn off swap:
+
+
+
+```
+ sudo swapoff /swapfile
+```
+
+
+
+2. Edit `/etc/fstab` and remove or comment out the line:
+
+
+
+```
+ /swapfile none swap sw 0 0
+```
+
+
+
+3. Delete the file:
+
+
+
+```
+ sudo rm /swapfile
+```
+
+
+
+After these steps, the system will go back to running without this swap file.
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md
new file mode 100644
index 000000000..0c2d7bc2b
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# Swap Partition and Swap File
+
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md
index b3fd78d3f..e64efbef3 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# System Update
+:::tip
+
+For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md).
+
+:::
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md
new file mode 100644
index 000000000..0c2d7bc2b
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# Swap Partition and Swap File
+
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md
index 36709c6fc..ea17467be 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# System Update
+:::tip
+
+For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md).
+
+:::
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md
new file mode 100644
index 000000000..0c2d7bc2b
--- /dev/null
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md
@@ -0,0 +1,9 @@
+---
+sidebar_position: 6
+---
+
+import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx';
+
+# Swap Partition and Swap File
+
+
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md
index 36709c6fc..ea17467be 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md
@@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat
# System Update
+:::tip
+
+For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md).
+
+:::
+