From 00d49bbbf7d3cb5b416601695639f95b8b8faaf0 Mon Sep 17 00:00:00 2001
From: Tw93 <tw93@qq.com>
Date: Mon, 13 Oct 2025 20:29:32 +0800
Subject: [PATCH] Fix the packaging appimage problem in linux

---
 README.md                   |   1 +
 README_CN.md                |   1 +
 bin/builders/BaseBuilder.ts |   5 +-
 bin/utils/shell.ts          |  19 ++-
 dist/cli.js                 |  18 ++-
 docs/faq.md                 | 248 ++++++++++++++++++++++++++++++++++++
 docs/faq_CN.md              | 248 ++++++++++++++++++++++++++++++++++++
 7 files changed, 534 insertions(+), 6 deletions(-)
 create mode 100644 docs/faq.md
 create mode 100644 docs/faq_CN.md

diff --git a/README.md b/README.md
index 37f4267..0d80258 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@
 - **Beginners**: Download ready-made [Popular Packages](#popular-packages) or use [Online Building](docs/github-actions-usage.md) with no environment setup required
 - **Developers**: Install [CLI Tool](docs/cli-usage.md) for one-command packaging of any website with customizable icons, window settings, and more
 - **Advanced Users**: Clone the project locally for [Custom Development](#development), or check [Advanced Usage](docs/advanced-usage.md) for style customization and feature enhancement
+- **Troubleshooting**: Check [FAQ](docs/faq.md) for common issues and solutions
 
 ## Popular Packages
 
diff --git a/README_CN.md b/README_CN.md
index 9a1872f..cb59686 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -29,6 +29,7 @@
 - **新手用户**：直接下载现成的 [常用包](#常用包下载)，或通过 [在线构建](docs/github-actions-usage_CN.md) 无需环境配置即可打包
 - **开发者**：安装 [CLI 工具](docs/cli-usage_CN.md) 后一行命令打包任意网站，支持自定义图标、窗口等参数
 - **高级用户**：本地克隆项目进行 [定制开发](#定制开发)，或查看 [高级用法](docs/advanced-usage_CN.md) 实现样式定制、功能增强
+- **遇到问题**：查看 [常见问题](docs/faq_CN.md) 获取常见问题的解决方案
 
 ## 常用包下载
 
diff --git a/bin/builders/BaseBuilder.ts b/bin/builders/BaseBuilder.ts
index 4d4ab81..0558741 100644
--- a/bin/builders/BaseBuilder.ts
+++ b/bin/builders/BaseBuilder.ts
@@ -164,7 +164,10 @@ export default abstract class BaseBuilder {
     // Show static message to keep the status visible
     logger.warn('✸ Building app...');
 
-    const buildEnv = this.getBuildEnvironment();
+    const buildEnv = {
+      ...this.getBuildEnvironment(),
+      ...(process.env.NO_STRIP && { NO_STRIP: process.env.NO_STRIP }),
+    };
 
     await shellExec(
       `cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`,
diff --git a/bin/utils/shell.ts b/bin/utils/shell.ts
index 09c3b1f..f8d6fcc 100644
--- a/bin/utils/shell.ts
+++ b/bin/utils/shell.ts
@@ -26,8 +26,21 @@ export async function shellExec(
       );
     }
 
-    throw new Error(
-      `Error occurred while executing command "${command}". Exit code: ${exitCode}. Details: ${errorMessage}`,
-    );
+    let errorMsg = `Error occurred while executing command "${command}". Exit code: ${exitCode}. Details: ${errorMessage}`;
+
+    if (
+      process.platform === 'linux' &&
+      (errorMessage.includes('linuxdeploy') ||
+        errorMessage.includes('appimage') ||
+        errorMessage.includes('strip'))
+    ) {
+      errorMsg +=
+        '\n\nLinux AppImage build error. Try one of these solutions:\n' +
+        '  1. Run with: NO_STRIP=true pake <url> --targets appimage\n' +
+        '  2. Use DEB format instead: pake <url> --targets deb\n' +
+        '  3. See detailed solutions: https://github.com/tw93/Pake/blob/main/docs/faq.md';
+    }
+
+    throw new Error(errorMsg);
   }
 }
diff --git a/dist/cli.js b/dist/cli.js
index 5aaceb6..f637d15 100755
--- a/dist/cli.js
+++ b/dist/cli.js
@@ -218,7 +218,18 @@ async function shellExec(command, timeout = 300000, env, showOutput = false) {
         if (error.timedOut) {
             throw new Error(`Command timed out after ${timeout}ms: "${command}". Try increasing timeout or check network connectivity.`);
         }
-        throw new Error(`Error occurred while executing command "${command}". Exit code: ${exitCode}. Details: ${errorMessage}`);
+        let errorMsg = `Error occurred while executing command "${command}". Exit code: ${exitCode}. Details: ${errorMessage}`;
+        if (process.platform === 'linux' &&
+            (errorMessage.includes('linuxdeploy') ||
+                errorMessage.includes('appimage') ||
+                errorMessage.includes('strip'))) {
+            errorMsg +=
+                '\n\nLinux AppImage build error. Try one of these solutions:\n' +
+                    '  1. Run with: NO_STRIP=true pake <url> --targets appimage\n' +
+                    '  2. Use DEB format instead: pake <url> --targets deb\n' +
+                    '  3. See detailed solutions: https://github.com/tw93/Pake/blob/main/docs/faq.md';
+        }
+        throw new Error(errorMsg);
     }
 }
 
@@ -784,7 +795,10 @@ class BaseBuilder {
         buildSpinner.stop();
         // Show static message to keep the status visible
         logger.warn('✸ Building app...');
-        const buildEnv = this.getBuildEnvironment();
+        const buildEnv = {
+            ...this.getBuildEnvironment(),
+            ...(process.env.NO_STRIP && { NO_STRIP: process.env.NO_STRIP }),
+        };
         await shellExec(`cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`, this.getBuildTimeout(), buildEnv);
         // Copy app
         const fileName = this.getFileName();
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..ce1cad1
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,248 @@
+# Frequently Asked Questions (FAQ)
+
+<h4 align="right"><strong>English</strong> | <a href="faq_CN.md">简体中文</a></h4>
+
+Common issues and solutions when using Pake.
+
+## Build Issues
+
+### Linux: AppImage Build Fails with "failed to run linuxdeploy"
+
+**Problem:**
+When building AppImage on Linux (Debian, Ubuntu, Arch, etc.), you may encounter errors like:
+
+```txt
+Error: failed to run linuxdeploy
+Error: strip: Unable to recognise the format of the input file
+```
+
+**Solution 1: Use NO_STRIP (Recommended)**
+
+Simply add `NO_STRIP=true` before your build command:
+
+```bash
+NO_STRIP=true pake https://example.com --name MyApp --targets appimage
+```
+
+This bypasses the library stripping process that often causes issues on certain Linux distributions.
+
+**Solution 2: Install System Dependencies**
+
+If NO_STRIP doesn't work, ensure you have all required system dependencies:
+
+```bash
+sudo apt update
+sudo apt install -y \
+  libdbus-1-dev \
+  libsoup-3.0-dev \
+  libjavascriptcoregtk-4.1-dev \
+  libwebkit2gtk-4.1-dev \
+  build-essential \
+  curl wget file \
+  libxdo-dev \
+  libssl-dev \
+  libgtk-3-dev \
+  libayatana-appindicator3-dev \
+  librsvg2-dev \
+  gnome-video-effects \
+  libglib2.0-dev \
+  libgirepository1.0-dev \
+  pkg-config
+```
+
+Then try building again with `NO_STRIP=true`.
+
+**Solution 3: Use DEB Format Instead**
+
+DEB packages are more stable on Debian-based systems:
+
+```bash
+pake https://example.com --name MyApp --targets deb
+```
+
+**Solution 4: Use Docker**
+
+Build in a clean environment without installing dependencies:
+
+```bash
+docker run --rm -v $(pwd)/output:/app/output \
+  ghcr.io/tw93/pake:latest \
+  pake https://example.com --name MyApp --targets appimage
+```
+
+**Why This Happens:**
+
+This is a known issue with Tauri's linuxdeploy tool, which can fail when:
+
+- System libraries have incompatible formats for stripping
+- 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.
+
+---
+
+### Linux: "cargo: command not found" After Installing Rust
+
+**Problem:**
+You installed Rust but Pake still reports "cargo: command not found".
+
+**Solution:**
+
+Pake CLI automatically reloads the Rust environment, but if issues persist:
+
+```bash
+# Reload environment in current terminal
+source ~/.cargo/env
+
+# Or restart your terminal
+```
+
+Then try building again.
+
+---
+
+### macOS: Build Fails with Module Compilation Errors
+
+**Problem:**
+On macOS 26 Beta or newer, you may see errors related to `CoreFoundation` or `_Builtin_float` modules.
+
+**Solution:**
+
+Create a configuration file to use compatible SDK:
+
+```bash
+cat > src-tauri/.cargo/config.toml << 'EOF'
+[env]
+MACOSX_DEPLOYMENT_TARGET = "15.0"
+SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
+EOF
+```
+
+This file is already in `.gitignore` and won't be committed.
+
+---
+
+### Windows: Missing Visual Studio Build Tools
+
+**Problem:**
+Build fails with errors about missing MSVC or Windows SDK.
+
+**Solution:**
+
+Install Visual Studio Build Tools:
+
+1. Download [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
+2. During installation, select "Desktop development with C++"
+3. For ARM64 support: Also select "MSVC v143 - VS 2022 C++ ARM64 build tools" under Individual Components
+
+---
+
+## Runtime Issues
+
+### App Window is Too Small/Large
+
+**Solution:**
+
+Specify custom dimensions when building:
+
+```bash
+pake https://example.com --width 1200 --height 800
+```
+
+See [CLI Usage Guide](cli-usage.md#window-options) for all window options.
+
+---
+
+### App Icon Not Showing Correctly
+
+**Problem:**
+Custom icon doesn't appear or shows default icon.
+
+**Solution:**
+
+Ensure you're using the correct icon format for your platform:
+
+- **macOS**: `.icns` format
+- **Windows**: `.ico` format
+- **Linux**: `.png` format
+
+```bash
+# macOS
+pake https://example.com --icon ./icon.icns
+
+# Windows
+pake https://example.com --icon ./icon.ico
+
+# Linux
+pake https://example.com --icon ./icon.png
+```
+
+Pake can automatically convert icons, but providing the correct format is more reliable.
+
+---
+
+### Website Features Not Working (Login, Upload, etc.)
+
+**Problem:**
+Some website features don't work in the Pake app.
+
+**Solution:**
+
+This is usually due to web compatibility issues. Try:
+
+1. **Set custom User Agent:**
+
+   ```bash
+   pake https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+   ```
+
+2. **Inject custom JavaScript:**
+
+   ```bash
+   pake https://example.com --inject ./fix.js
+   ```
+
+3. **Check if the site requires specific permissions** that may not be available in WebView
+
+---
+
+## Installation Issues
+
+### Permission Denied When Installing Globally
+
+**Problem:**
+`npm install -g pake-cli` fails with permission errors.
+
+**Solution:**
+
+Use one of these approaches:
+
+```bash
+# Option 1: Use npx (no installation needed)
+npx pake-cli https://example.com
+
+# Option 2: Fix npm permissions
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+npm install -g pake-cli
+
+# Option 3: Use pnpm (recommended)
+pnpm install -g pake-cli
+```
+
+---
+
+## Getting Help
+
+If your issue isn't covered here:
+
+1. Check the [CLI Usage Guide](cli-usage.md) for detailed parameter documentation
+2. See [Advanced Usage](advanced-usage.md) for prerequisites and system setup
+3. Search [existing GitHub issues](https://github.com/tw93/Pake/issues)
+4. [Open a new issue](https://github.com/tw93/Pake/issues/new) with:
+   - Your OS and version
+   - Node.js and Rust versions (`node --version`, `rustc --version`)
+   - Complete error message
+   - Build command you used
diff --git a/docs/faq_CN.md b/docs/faq_CN.md
new file mode 100644
index 0000000..e5606c9
--- /dev/null
+++ b/docs/faq_CN.md
@@ -0,0 +1,248 @@
+# 常见问题 (FAQ)
+
+<h4 align="right"><a href="faq.md">English</a> | <strong>简体中文</strong></h4>
+
+使用 Pake 时的常见问题和解决方案。
+
+## 构建问题
+
+### Linux：AppImage 构建失败，提示 "failed to run linuxdeploy"
+
+**问题描述：**
+在 Linux 系统（Debian、Ubuntu、Arch 等）上构建 AppImage 时，可能遇到如下错误：
+
+```txt
+Error: failed to run linuxdeploy
+Error: strip: Unable to recognise the format of the input file
+```
+
+**解决方案 1：使用 NO_STRIP（推荐）**
+
+在构建命令前加上 `NO_STRIP=true`：
+
+```bash
+NO_STRIP=true pake https://example.com --name MyApp --targets appimage
+```
+
+这会绕过经常在某些 Linux 发行版上出现问题的库文件剥离过程。
+
+**解决方案 2：安装系统依赖**
+
+如果 NO_STRIP 不起作用，确保已安装所有必需的系统依赖：
+
+```bash
+sudo apt update
+sudo apt install -y \
+  libdbus-1-dev \
+  libsoup-3.0-dev \
+  libjavascriptcoregtk-4.1-dev \
+  libwebkit2gtk-4.1-dev \
+  build-essential \
+  curl wget file \
+  libxdo-dev \
+  libssl-dev \
+  libgtk-3-dev \
+  libayatana-appindicator3-dev \
+  librsvg2-dev \
+  gnome-video-effects \
+  libglib2.0-dev \
+  libgirepository1.0-dev \
+  pkg-config
+```
+
+然后使用 `NO_STRIP=true` 再次尝试构建。
+
+**解决方案 3：改用 DEB 格式**
+
+DEB 包在基于 Debian 的系统上更稳定：
+
+```bash
+pake https://example.com --name MyApp --targets deb
+```
+
+**解决方案 4：使用 Docker**
+
+在干净的环境中构建，无需安装依赖：
+
+```bash
+docker run --rm -v $(pwd)/output:/app/output \
+  ghcr.io/tw93/pake:latest \
+  pake https://example.com --name MyApp --targets appimage
+```
+
+**原因：**
+
+这是 Tauri 的 linuxdeploy 工具的已知问题，在以下情况下可能失败：
+
+- 系统库的格式不兼容剥离操作
+- 在较新的发行版上构建（Arch、Debian Trixie 等）
+- 缺少 WebKit2GTK 或 GTK 开发库
+
+`NO_STRIP=true` 环境变量是 Tauri 社区推荐的官方解决方法。
+
+---
+
+### Linux："cargo: command not found" 即使已安装 Rust
+
+**问题描述：**
+已安装 Rust 但 Pake 仍然提示 "cargo: command not found"。
+
+**解决方案：**
+
+Pake CLI 会自动重新加载 Rust 环境，但如果问题仍然存在：
+
+```bash
+# 在当前终端重新加载环境
+source ~/.cargo/env
+
+# 或者重启终端
+```
+
+然后再次尝试构建。
+
+---
+
+### macOS：构建失败，出现模块编译错误
+
+**问题描述：**
+在 macOS 26 Beta 或更新版本上，可能看到与 `CoreFoundation` 或 `_Builtin_float` 模块相关的错误。
+
+**解决方案：**
+
+创建配置文件以使用兼容的 SDK：
+
+```bash
+cat > src-tauri/.cargo/config.toml << 'EOF'
+[env]
+MACOSX_DEPLOYMENT_TARGET = "15.0"
+SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
+EOF
+```
+
+此文件已在 `.gitignore` 中，不会被提交。
+
+---
+
+### Windows：缺少 Visual Studio 构建工具
+
+**问题描述：**
+构建失败，提示缺少 MSVC 或 Windows SDK。
+
+**解决方案：**
+
+安装 Visual Studio 构建工具：
+
+1. 下载 [Visual Studio Build Tools](https://visualstudio.microsoft.com/zh-hans/downloads/#build-tools-for-visual-studio-2022)
+2. 安装时选择"使用 C++ 的桌面开发"
+3. ARM64 支持：在"单个组件"下额外选择"MSVC v143 - VS 2022 C++ ARM64 构建工具"
+
+---
+
+## 运行时问题
+
+### 应用窗口太小/太大
+
+**解决方案：**
+
+构建时指定自定义尺寸：
+
+```bash
+pake https://example.com --width 1200 --height 800
+```
+
+查看 [CLI 使用指南](cli-usage_CN.md#窗口选项) 了解所有窗口选项。
+
+---
+
+### 应用图标显示不正确
+
+**问题描述：**
+自定义图标没有显示或显示默认图标。
+
+**解决方案：**
+
+确保为您的平台使用正确的图标格式：
+
+- **macOS**：`.icns` 格式
+- **Windows**：`.ico` 格式
+- **Linux**：`.png` 格式
+
+```bash
+# macOS
+pake https://example.com --icon ./icon.icns
+
+# Windows
+pake https://example.com --icon ./icon.ico
+
+# Linux
+pake https://example.com --icon ./icon.png
+```
+
+Pake 可以自动转换图标，但提供正确的格式更可靠。
+
+---
+
+### 网站功能不工作（登录、上传等）
+
+**问题描述：**
+某些网站功能在 Pake 应用中无法工作。
+
+**解决方案：**
+
+这通常是由于 Web 兼容性问题。尝试：
+
+1. **设置自定义 User Agent：**
+
+   ```bash
+   pake https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+   ```
+
+2. **注入自定义 JavaScript：**
+
+   ```bash
+   pake https://example.com --inject ./fix.js
+   ```
+
+3. **检查网站是否需要 WebView 中可能不可用的特定权限**
+
+---
+
+## 安装问题
+
+### 全局安装时权限被拒绝
+
+**问题描述：**
+`npm install -g pake-cli` 失败，提示权限错误。
+
+**解决方案：**
+
+使用以下方法之一：
+
+```bash
+# 方案 1：使用 npx（无需安装）
+npx pake-cli https://example.com
+
+# 方案 2：修复 npm 权限
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+npm install -g pake-cli
+
+# 方案 3：使用 pnpm（推荐）
+pnpm install -g pake-cli
+```
+
+---
+
+## 获取帮助
+
+如果您的问题未在此处涵盖：
+
+1. 查看 [CLI 使用指南](cli-usage_CN.md) 了解详细参数文档
+2. 参阅 [高级用法](advanced-usage_CN.md) 了解前置条件和系统设置
+3. 搜索 [现有的 GitHub issues](https://github.com/tw93/Pake/issues)
+4. [提交新 issue](https://github.com/tw93/Pake/issues/new) 时请包含：
+   - 您的操作系统和版本
+   - Node.js 和 Rust 版本（`node --version`、`rustc --version`）
+   - 完整的错误信息
+   - 您使用的构建命令