跳至主要内容
版本：v2.9.0

故障排除

各种故障排除技巧。

wails 命令似乎不见了？​

如果您的系统报告 wails 命令丢失，请确保您已正确遵循 Go 安装指南。通常，这意味着您用户主目录中的 go/bin 目录不在 PATH 环境变量中。您通常还需要关闭并重新打开任何打开的命令提示符，以便在命令提示符中反映安装程序对环境所做的更改。

我的应用程序显示一个白色/空白屏幕​

检查您的应用程序是否包含来自正确目录的资产。在您的 main.go 文件中，您将拥有类似以下代码的内容

//go:embed all:frontend/dist
var assets embed.FS

检查 frontend/dist 是否包含您的应用程序资产。

Mac​

如果这发生在 Mac 上，请尝试将以下内容添加到您的 Info.plist 中

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

参考：https://github.com/wailsapp/wails/issues/1504#issuecomment-1174317433

Mac 应用程序无效​

如果您的构建应用程序在查找器中看起来像这样

这很可能是因为您的应用程序的 info.plist 无效。更新 build/<yourapp>.app/Contents/info.plist 中的文件，并检查数据是否有效，例如检查二进制名称是否正确。要保留更改，请将文件复制回 build/darwin 目录。

我的应用程序在 Windows 资源管理器中没有显示正确的图标​

如果您的应用程序没有显示正确的图标，请尝试删除位于 C:\Users\<your username>\AppData\Local 目录中的隐藏 IconCache.db 文件。这将强制 Windows 重新构建图标缓存。

来源：https://github.com/wailsapp/wails/issues/2360#issuecomment-1556070036

无法使用可变参数从前端调用后端方法​

如果您有一个使用可变参数定义的后端方法，例如

func (a *App) TestFunc(msg string, args ...interface{}) error {
    // Code
}

从前端像这样调用此方法将失败

var msg = "Hello: ";
var args = ["Go", "JS"];
window.go.main.App.TestFunc(msg, ...args)
  .then((result) => {
    //do things here
  })
  .catch((error) => {
    //handle error
  });

解决方法

var msg = "Hello ";
var args = ["Go", "JS"];
window.go.main.App.TestFunc(msg, args)
  .then((result) => {
    //without the 3 dots
    //do things here
  })
  .catch((error) => {
    //handle error
  });

鸣谢：https://github.com/wailsapp/wails/issues/1186

我在尝试安装 Wails 时遇到代理错误​

如果您遇到类似这样的错误

"https://proxy.golang.org/github.com/wailsapp/wails/cmd/wails/@v/list": dial tcp 172.217.163.49:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.

这可能是因为官方 Go 代理被阻止（中国的用户报告了这种情况）。解决方案是手动设置代理，例如

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct

来源：https://github.com/wailsapp/wails/issues/1233

生成的 TypeScript 没有正确的类型​

有时生成的 TypeScript 没有正确的类型。为了减轻这种情况，可以使用 ts_type 结构标记指定应生成哪些类型。有关更多详细信息，请阅读此。

当我从 index.html 导航离开时，我无法在前端调用方法​

如果您从 index.html 导航到一个新的 html 文件，上下文将丢失。这可以通过将以下导入添加到您导航到的任何新页面的 <head> 部分来解决

<head>
  <script src="/wails/ipc.js"></script>
  <script src="/wails/runtime.js"></script>
</head>

来源：https://github.com/wailsapp/wails/discussions/1512

我在 Mac 上运行 wails dev 时收到 too many open files 错误​

默认情况下，macOS 仅允许您打开最多 256 个文件。这可能会影响 wails dev 命令。可以通过在终端中运行以下命令来增加此限制：ulimit -n 1024。

FSNotify 正在寻求迁移到 Apple 的 fsevents 用于 Mac。如果此事不能尽快完成，我们将创建我们自己的实现，跟踪这里。

我的 Mac 应用程序出现奇怪的编译错误​

一些用户报告说看到了以下编译错误

# github.com/wailsapp/wails/v2/internal/frontend/desktop/darwin
In file included from ../../pkg/mod/github.com/wailsapp/wails/[email protected]/internal/frontend/desktop/darwin/callbacks.go:9:
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/Foundation.h:12:
/Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h:91:143: error: function does not return NSString
- (NSAttributedString *)localizedAttributedStringForKey:(NSString *)key value:(nullable NSString *)value table:(nullable NSString *)tableName NS_FORMAT_ARGUMENT(1) NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
                                                         ~~~~~~~~~~~~~~                                                                       ^                  ~
/Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSObjCRuntime.h:103:48: note: expanded from macro 'NS_FORMAT_ARGUMENT'
        #define NS_FORMAT_ARGUMENT(A) __attribute__ ((format_arg(A)))

这通常是由于您运行的 OS 版本与安装的 XCode 命令行工具版本不匹配导致的。如果您看到这样的错误，请尝试将您的 XCode 命令行工具升级到最新版本。

如果重新安装 Xcode 命令工具仍然失败，您可以使用以下命令检查工具包所在的路径

xcode-select -p

如果显示 /Applications/Xcode.app/Contents/Developer，请运行 sudo xcode-select --switch /Library/Developer/CommandLineTools

来源：https://github.com/wailsapp/wails/issues/1806 和 https://github.com/wailsapp/wails/issues/1140#issuecomment-1290446496

我的应用程序无法在 Mac 上编译​

如果您遇到类似这样的错误

l1@m2 GoEasyDesigner % go build -tags dev -gcflags "all=-N -l"
/Users/l1/sdk/go1.20.5/pkg/tool/darwin_arm64/link: running clang failed: exit status 1
Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_UTType", referenced from:
      objc-class-ref in 000016.o
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

确保您安装了最新的 SDK。如果安装了最新的 SDK 但您仍然遇到此问题，请尝试以下操作

export CGO_LDFLAGS="-framework UniformTypeIdentifiers" && go build -tags dev -gcflags "all=-N -l"

来源：https://github.com/wailsapp/wails/pull/2925#issuecomment-1726828562

--

无法启动服务：主机版本“x.x.x 与二进制版本“x.x.x”不匹配​

最好将 frontend/node_modules 和 frontend/package-lock.json 添加到您的 .gitignore 中。否则，当您在可能安装了不同版本的 Node 的另一台机器上打开您的存储库时，您可能无法运行您的应用程序。

如果确实发生了这种情况，只需删除 frontend/node_modules 和 frontend/package-lock.json 然后再次运行您的 wails build 或 wails dev 命令。

构建过程卡在“生成绑定”上​

绑定生成过程以特殊模式运行您的应用程序。如果应用程序有意或无意地包含一个无限循环（即在 wails.Run() 完成后不退出），这会导致构建过程卡在绑定生成阶段。请确保您的代码正常退出。

Mac 应用程序在启动时闪烁白色​

这是因为 webview 的默认背景是白色。如果您想使用窗口背景色，可以使用以下配置使 webview 背景透明

    err := wails.Run(&options.App{
        Title:  "macflash",
        Width:  1024,
        Height: 768,
        // Other settings
        Mac: &mac.Options{
            WebviewIsTransparent: true,
        },
    })

我在 Windows 上以管理员身份运行程序时收到“Microsoft Edge 无法读取或写入其数据目录”错误​

您将程序设置为需要管理员权限，效果很好！不幸的是，一些用户在运行它时看到“Microsoft Edge 无法读取或写入其数据目录”错误。

当一台 Windows 机器有两个本地帐户时

  • Alice，管理员
  • Bob，普通用户

Bob 在运行您的程序时看到一个 UAC 提示。Bob 在此提示中输入 Alice 的管理员凭据。应用程序以管理员权限在 Alice 的帐户下启动。

Wails 指示 WebView2 在指定的 WebviewUserDataPath 处存储用户数据。它默认为 %APPDATA%\[BinaryName.exe]。

因为应用程序是在 Alice 的帐户下运行的，所以 %APPDATA%\[BinaryName.exe] 解析为 C:\Users\Alice\AppData\Roaming\[BinaryName.exe]。

WebView2 在 Bob 的登录帐户下创建一些子进程，而不是 Alice 的管理员帐户。由于 Bob 无法访问 C:\Users\Alice\AppData\Roaming\[BinaryName.exe]，因此显示了“Microsoft Edge 无法读取或写入其数据目录”错误。

可能的解决方案 #1

重构您的应用程序以在没有持续管理员权限的情况下工作。如果您只需要执行一小部分管理员任务（例如运行更新程序），则可以使用最低权限运行您的应用程序，然后使用 runas 命令根据需要以管理员权限运行这些任务

//go:build windows

package sample

import (
    "golang.org/x/sys/windows"
    "syscall"
)

// Calling RunAs("C:\path\to\my\updater.exe") shows Bob a UAC prompt. Bob enters Alice's admin credentials. The updater launches with admin permissions under Alice's account.
func RunAs(path string) error {
    verbPtr, _ := syscall.UTF16PtrFromString("runas")
    exePtr, _ := syscall.UTF16PtrFromString(path)
    cwdPtr, _ := syscall.UTF16PtrFromString("")
    argPtr, _ := syscall.UTF16PtrFromString("")

    var showCmd int32 = 1 //SW_NORMAL

    err := windows.ShellExecute(0, verbPtr, exePtr, argPtr, cwdPtr, showCmd)
    if err != nil {
        return err
    }
    return nil
}

可能的解决方案 #2

使用扩展权限运行您的应用程序。如果您绝对必须使用持续管理员权限，则如果您使用两个用户都可以访问的数据目录，并且您还使用 SeBackupPrivilege、SeDebugPrivilege 和 SeRestorePrivilege 权限启动您的应用程序，WebView2 将正常运行。这是一个示例

package main

import (
    "embed"
    "os"
    "runtime"

    "github.com/fourcorelabs/wintoken"
    "github.com/hectane/go-acl"
    "github.com/wailsapp/wails/v2"
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/assetserver"
    "github.com/wailsapp/wails/v2/pkg/options/windows"
)

//go:embed all:frontend/dist
var assets embed.FS

const (
    fixedTokenKey = "SAMPLE_RANDOM_KEY"
    fixedTokenVal = "with-fixed-token"
    webviewDir    = "C:\\ProgramData\\Sample"
)

func runWithFixedToken() {
    println("Re-launching self")
    token, err := wintoken.OpenProcessToken(0, wintoken.TokenPrimary) //pass 0 for own process
    if err != nil {
        panic(err)
    }
    defer token.Close()

    token.EnableTokenPrivileges([]string{
        "SeBackupPrivilege",
        "SeDebugPrivilege",
        "SeRestorePrivilege",
    })

    cmd := exec.Command(os.Args[0])
    cmd.Args = os.Args
    cmd.Env = os.Environ()
    cmd.Env = append(cmd.Env, fmt.Sprintf("%v=%v", fixedTokenKey, fixedTokenVal))
    cmd.Stdin = os.Stdin
    cmd.Stdout = os.Stdout
    cmd.Stderr = os.Stderr
    cmd.SysProcAttr = &syscall.SysProcAttr{Token: syscall.Token(token.Token())}
    if err := cmd.Run(); err != nil {
        println("Error after launching self:", err)
        os.Exit(1)
    }
    println("Clean self launch :)")
    os.Exit(0)
}

func main() {
    if runtime.GOOS == "windows" && os.Getenv(fixedTokenKey) != fixedTokenVal {
        runWithFixedToken()
    }

    println("Setting data dir to", webviewDir)
    if err := os.MkdirAll(webviewDir, os.ModePerm); err != nil {
        println("Failed creating dir:", err)
    }
    if err := acl.Chmod(webviewDir, 0777); err != nil {
        println("Failed setting ACL on dir:", err)
    }

    app := NewApp()

    err := wails.Run(&options.App{
        Title:  "sample-data-dir",
        Width:  1024,
        Height: 768,
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
        Bind: []interface{}{
            app,
        },
        Windows: &windows.Options{
            WebviewUserDataPath: webviewDir,
        },
    })

    if err != nil {
        println("Error:", err.Error())
    }
}

如果您使用的是两个用户都可以访问的数据目录，但未使用扩展权限，您将收到 WebView2 80010108 The object invoked has disconnected from its clients 错误。

可能的未来解决方案 #3：如果实现了，使用内存中模式运行 WebView2。

WebView2 安装成功，但 wails doctor 命令显示它未安装​

如果你已经安装了 WebView2，但 wails doctor 命令显示它没有安装，则可能是安装的 WebView2 运行时是针对不同的架构。 你可以从 这里 下载正确的运行时。

来源：https://github.com/wailsapp/wails/issues/2917

WebVie2wProcess 失败，错误类型为​

如果你的 Windows 应用程序生成此类错误，你可以查看此错误的含义 这里。