docs/faq_CN.md
使用 Pake 时的常见问题和解决方案。
问题描述： 在构建 Pake 或使用 CLI 时，遇到如下错误：
error: failed to parse manifest
Caused by:
feature `edition2024` is required
this Cargo does not support nightly features, but if you switch to nightly channel you can add `cargo-features = ["edition2024"]`
to enable this feature
原因分析：
Pake 的依赖项需要 Rust edition2024 支持，该特性仅在 Rust 1.85.0 或更高版本中可用。具体来说：
tauri → image → moxcms → pxfm v0.1.25（需要 edition2024）解决方案：
将 Rust 工具链更新到 1.85.0 或更高版本：
# 更新到最新稳定版 Rust
rustup update stable
# 或者安装最新稳定版
rustup install stable
# 验证更新
rustc --version
# 应显示：rustc 1.85.0 或更高版本
更新后，重新执行构建命令。
对于开发环境设置：
如果您正在设置开发环境，请确保：
rustc --version 检查）node --version 检查）详见 CONTRIBUTING.md 获取完整的前置条件。
问题描述： 在 Ubuntu 24.04 或更新版本上构建时，可能遇到以下错误：
Can't detect any appindicator library
或者在之前的版本中可能看到关于 Icon RGBA 的报错。
解决方案：
这是因为 Ubuntu 24.04+ 使用 libayatana-appindicator3-dev 替代了旧的 libappindicator3-dev。
请安装正确的依赖库：
sudo apt-get update
sudo apt-get install -y libayatana-appindicator3-dev
问题描述： 在 Linux 系统（Debian、Ubuntu、Arch 等）上构建 AppImage 时，可能遇到如下错误：
Error: failed to run linuxdeploy
Error: strip: Unable to recognise the format of the input file
解决方案 1：自动 NO_STRIP 重试（推荐）
Pake CLI 已在 linuxdeploy 剥离失败时自动使用 NO_STRIP=1 进行二次构建。如果你希望一开始就跳过剥离步骤（或在脚本中使用），可以手动设置该变量：
NO_STRIP=1 pake https://example.com --name MyApp --targets appimage
这会绕过经常在某些 Linux 发行版上出现问题的库文件剥离过程。
解决方案 2：安装系统依赖
如果 NO_STRIP 不起作用，确保已安装所有必需的系统依赖：
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=1）。
解决方案 3：改用 DEB 格式
DEB 包在基于 Debian 的系统上更稳定：
pake https://example.com --name MyApp --targets deb
解决方案 4：使用 Docker（需开放 FUSE）
在干净的环境中构建，无需安装依赖。AppImage 工具需要访问 /dev/fuse，因此需要以特权模式运行（或显式授权 FUSE）：
docker run --rm --privileged \
--device /dev/fuse \
--security-opt apparmor=unconfined \
-v $(pwd)/output:/output \
ghcr.io/tw93/pake:latest \
https://example.com --name MyApp --targets appimage
提示： 生成的 AppImage 可能属于 root，需要执行
sudo chown $(id -nu):$(id -ng) ./output/MyApp.AppImage调整所有权。
原因：
这是 Tauri 的 linuxdeploy 工具的已知问题，在以下情况下可能失败：
NO_STRIP=1 环境变量是 Tauri 社区推荐的官方解决方法。
问题描述： 已安装 Rust 但 Pake 仍然提示 "cargo: command not found"。
解决方案：
Pake CLI 会自动重新加载 Rust 环境，但如果问题仍然存在：
# 在当前终端重新加载环境
source ~/.cargo/env
# 或者重启终端
然后再次尝试构建。
问题描述： 在 Windows 上首次构建时，可能遇到：
Error: Command timed out after 900000ms: "cd ... && pnpm install"
原因分析：
Windows 首次安装可能较慢，原因包括：
解决方案 1：自动重试（内置）
Pake CLI 现在会在初次安装超时后自动使用国内镜像重试。只需等待重试完成即可。
解决方案 2：手动安装依赖
如果自动重试失败，可手动安装依赖：
# 进入 pake-cli 安装目录
cd %LOCALAPPDATA%\pnpm\global\5\.pnpm\pake-cli@版本号\node_modules\pake-cli
# 使用国内镜像安装
pnpm install --registry=https://registry.npmmirror.com
# 然后重新构建
pake https://github.com --name GitHub
解决方案 3：改善网络环境
预期时间：
问题描述： 构建失败，提示缺少 MSVC 或 Windows SDK。
解决方案：
安装 Visual Studio 构建工具：
问题描述：
在 macOS 26 Beta 或更新版本上，可能看到与 CoreFoundation 或 _Builtin_float 模块相关的错误。
解决方案：
创建配置文件以使用兼容的 SDK：
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 中，不会被提交。
解决方案：
构建时指定自定义尺寸：
pake https://example.com --width 1200 --height 800
查看 CLI 使用指南 了解所有窗口选项。
问题描述： 自定义图标没有显示或显示默认图标。
解决方案：
确保为您的平台使用正确的图标格式：
.icns 格式.ico 格式.png 格式# 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 兼容性问题。尝试：
设置自定义 User Agent：
pake https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
注入自定义 JavaScript：
pake https://example.com --inject ./fix.js
对于需要定时刷新的页面，建议把这类行为放在一个小的注入脚本里，而不是增加专门的 Pake 参数：
function isEditing(element) {
if (!element) return false;
const tagName = element.tagName;
return (
element.isContentEditable ||
tagName === "INPUT" ||
tagName === "TEXTAREA" ||
tagName === "SELECT"
);
}
setInterval(() => {
if (!document.hidden && !isEditing(document.activeElement)) {
window.location.reload();
}
}, 300000);
将其保存为 refresh.js，然后这样打包：
pake https://news.ycombinator.com --name HackerNews --inject ./refresh.js
检查网站是否需要 WebView 中可能不可用的特定权限
注意嵌入式 WebView 的登录限制
某些认证提供方，尤其是 Google，可能会阻止在嵌入式 WebView 中完成登录。由于 Pake 是把网站包装进桌面 WebView，Google 自家站点或依赖 Google OAuth 的网站，即使启用了 --new-window 或 --multi-window，也仍然可能无法在应用内完成登录。这属于提供方策略限制，不是打包逻辑错误。遇到这种情况时，建议改用普通浏览器、浏览器安装版站点应用，或官方原生桌面客户端。
问题描述：
npm install -g pake-cli 失败，提示权限错误。
解决方案：
使用以下方法之一：
# 方案 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
如果您的问题未在此处涵盖：
node --version、rustc --version）Can't detect any appindicator library问题描述： 在 Linux 上打包时，构建失败并显示以下错误：
Can't detect any appindicator library
原因分析：
这个错误表示您的 Linux 系统缺少创建“系统托盘图标”所需的核心库 libappindicator。Pake 打包的应用支持系统托盘功能，因此该库是必需的。
解决方案： 您需要在您的 Linux 系统上安装这个缺失的开发库。
对于 Debian / Ubuntu 系统：
sudo apt-get update && sudo apt-get install -y libappindicator3-dev
对于 Fedora / CentOS / RHEL 系统：
sudo dnf install -y libappindicator-devel
为了确保打包环境的完整性，推荐一次性安装所有 Tauri 所需的依赖。请参考本文档中关于 failed to run linuxdeploy 问题的解决方案，其中包含了完整的依赖列表。