lostecho/Pake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix the packaging appimage problem in linux

Browse Source
This commit is contained in:
Tw93
2025-10-13 20:29:32 +08:00
parent 2fb47988fc
commit 00d49bbbf7
7 changed files with 534 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@@ -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

1
README_CN.md
View File

@@ -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) 获取常见问题的解决方案
## 常用包下载

5
bin/builders/BaseBuilder.ts vendored
View File

@@ -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)}`,

19
bin/utils/shell.ts vendored
View File

@@ -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);
}
}

18
dist/cli.js vendored
View File

@@ -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();

248
docs/faq.md Normal file
View File

@@ -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

248
docs/faq_CN.md Normal file
View File

@@ -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`）
- 完整的错误信息
- 您使用的构建命令