Merge branch 'dev'

docs/cli-usage.md

@@ -438,16 +438,19 @@ After completing the above steps, your application should be successfully packag
 ## Docker
 
 ```shell
-# On Linux, you can run the Pake CLI via Docker
-docker run -it --rm \ # Run interactively, remove container after exit
-    -v YOUR_DIR:/output \ # Files from container's /output will be in YOU_DIR
+# Run the Pake CLI via Docker (AppImage builds need FUSE access)
+docker run --rm --privileged \
+    --device /dev/fuse \
+    --security-opt apparmor=unconfined \
+    -v YOUR_DIR:/output \
     ghcr.io/tw93/pake \
     <arguments>
 
 # For example:
-docker run -it --rm \
+docker run --rm --privileged \
+    --device /dev/fuse \
+    --security-opt apparmor=unconfined \
     -v ./packages:/output \
     ghcr.io/tw93/pake \
-    https://example.com --name myapp --icon ./icon.png
-
+    https://example.com --name myapp --icon ./icon.png --targets appimage
 ```

docs/cli-usage_CN.md

@@ -436,16 +436,19 @@ pake ./my-app/index.html --name "my-app" --use-local-file
 ## Docker 使用
 
 ```shell
-# 在Linux上，您可以通过 Docker 运行 Pake CLI。
-docker run -it --rm \ # Run interactively, remove container after exit
-    -v YOUR_DIR:/output \ # Files from container's /output will be in YOU_DIR
+# 在 Linux 上通过 Docker 运行 Pake CLI（AppImage 构建需要 FUSE 权限）
+docker run --rm --privileged \
+    --device /dev/fuse \
+    --security-opt apparmor=unconfined \
+    -v YOUR_DIR:/output \
     ghcr.io/tw93/pake \
     <arguments>
 
-# For example:
-docker run -it --rm \
+# 例如：
+docker run --rm --privileged \
+    --device /dev/fuse \
+    --security-opt apparmor=unconfined \
     -v ./packages:/output \
     ghcr.io/tw93/pake \
-    https://example.com --name MyApp --icon ./icon.png
-
+    https://example.com --name MyApp --icon ./icon.png --targets appimage
 ```

docs/faq.md

@@ -16,12 +16,12 @@ Error: failed to run linuxdeploy
 Error: strip: Unable to recognise the format of the input file
 ```
 
-**Solution 1: Use NO_STRIP (Recommended)**
+**Solution 1: Automatic NO_STRIP Retry (Recommended)**
 
-Simply add `NO_STRIP=true` before your build command:
+Pake CLI now automatically retries AppImage builds with `NO_STRIP=1` when linuxdeploy fails to strip the binary. To skip the strip step from the very first attempt (or when scripting your own builds), set the variable manually:
 
 ```bash
-NO_STRIP=true pake https://example.com --name MyApp --targets appimage
+NO_STRIP=1 pake https://example.com --name MyApp --targets appimage
 ```
 
 This bypasses the library stripping process that often causes issues on certain Linux distributions.
@@ -50,7 +50,7 @@ sudo apt install -y \
   pkg-config
 ```
 
-Then try building again with `NO_STRIP=true`.
+Then try building again (you can still pre-set `NO_STRIP=1` if you prefer).
 
 **Solution 3: Use DEB Format Instead**
 
@@ -60,16 +60,21 @@ DEB packages are more stable on Debian-based systems:
 pake https://example.com --name MyApp --targets deb
 ```
 
-**Solution 4: Use Docker**
+**Solution 4: Use Docker (with FUSE access)**
 
-Build in a clean environment without installing dependencies:
+Build in a clean environment without installing dependencies. AppImage tooling needs access to `/dev/fuse`, so run the container in privileged mode (or grant FUSE explicitly):
 
 ```bash
-docker run --rm -v $(pwd)/output:/app/output \
+docker run --rm --privileged \
+  --device /dev/fuse \
+  --security-opt apparmor=unconfined \
+  -v $(pwd)/output:/output \
   ghcr.io/tw93/pake:latest \
-  pake https://example.com --name MyApp --targets appimage
+  https://example.com --name MyApp --targets appimage
 ```
 
+> **Tip:** The generated AppImage may be owned by root. Run `sudo chown $(id -nu):$(id -ng) ./output/MyApp.AppImage` afterwards.
+
 **Why This Happens:**
 
 This is a known issue with Tauri's linuxdeploy tool, which can fail when:
@@ -78,7 +83,7 @@ This is a known issue with Tauri's linuxdeploy tool, which can fail when:
 - Building on newer distributions (Arch, Debian Trixie, etc.)
 - Missing WebKit2GTK or GTK development libraries
 
-The `NO_STRIP=true` environment variable is the official workaround recommended by the Tauri community.
+The `NO_STRIP=1` environment variable is the official workaround recommended by the Tauri community.
 
 ---
 

docs/faq_CN.md

@@ -16,12 +16,12 @@ Error: failed to run linuxdeploy
 Error: strip: Unable to recognise the format of the input file
 ```
 
-**解决方案 1：使用 NO_STRIP（推荐）**
+**解决方案 1：自动 NO_STRIP 重试（推荐）**
 
-在构建命令前加上 `NO_STRIP=true`：
+Pake CLI 已在 linuxdeploy 剥离失败时自动使用 `NO_STRIP=1` 进行二次构建。如果你希望一开始就跳过剥离步骤（或在脚本中使用），可以手动设置该变量：
 
 ```bash
-NO_STRIP=true pake https://example.com --name MyApp --targets appimage
+NO_STRIP=1 pake https://example.com --name MyApp --targets appimage
 ```
 
 这会绕过经常在某些 Linux 发行版上出现问题的库文件剥离过程。
@@ -50,7 +50,7 @@ sudo apt install -y \
   pkg-config
 ```
 
-然后使用 `NO_STRIP=true` 再次尝试构建。
+然后再次尝试构建（也可以提前设置 `NO_STRIP=1`）。
 
 **解决方案 3：改用 DEB 格式**
 
@@ -60,16 +60,21 @@ DEB 包在基于 Debian 的系统上更稳定：
 pake https://example.com --name MyApp --targets deb
 ```
 
-**解决方案 4：使用 Docker**
+**解决方案 4：使用 Docker（需开放 FUSE）**
 
-在干净的环境中构建，无需安装依赖：
+在干净的环境中构建，无需安装依赖。AppImage 工具需要访问 `/dev/fuse`，因此需要以特权模式运行（或显式授权 FUSE）：
 
 ```bash
-docker run --rm -v $(pwd)/output:/app/output \
+docker run --rm --privileged \
+  --device /dev/fuse \
+  --security-opt apparmor=unconfined \
+  -v $(pwd)/output:/output \
   ghcr.io/tw93/pake:latest \
-  pake https://example.com --name MyApp --targets appimage
+  https://example.com --name MyApp --targets appimage
 ```
 
+> **提示：** 生成的 AppImage 可能属于 root，需要执行 `sudo chown $(id -nu):$(id -ng) ./output/MyApp.AppImage` 调整所有权。
+
 **原因：**
 
 这是 Tauri 的 linuxdeploy 工具的已知问题，在以下情况下可能失败：
@@ -78,7 +83,7 @@ docker run --rm -v $(pwd)/output:/app/output \
 - 在较新的发行版上构建（Arch、Debian Trixie 等）
 - 缺少 WebKit2GTK 或 GTK 开发库
 
-`NO_STRIP=true` 环境变量是 Tauri 社区推荐的官方解决方法。
+`NO_STRIP=1` 环境变量是 Tauri 社区推荐的官方解决方法。
 
 ---