Fix the packaging appimage problem in linux

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