babalae/better-genshin-impact · warning · ArgumentException

文件路径 '{path}' 包含非法字符

Error message

文件路径 '{path}' 包含非法字符

What it means

Thrown by ScriptUtils.NormalizePath when the file-name portion of the input path contains characters considered invalid for file names by the OS (Path.GetInvalidFileNameChars — e.g., <, >, |, ", :, or control chars on Windows). The check inspects only the GetFileName portion.

Source

Thrown at BetterGenshinImpact/Core/Script/Utils/ScriptUtils.cs:23

namespace BetterGenshinImpact.Core.Script.Utils;

public class ScriptUtils
{
    /// <summary>
    /// Normalize and validate a path.
    /// </summary>
    public static string NormalizePath(string root, string path)
    {
        // 校验空字符串
        if (string.IsNullOrWhiteSpace(path))
            throw new ArgumentException("文件路径不能为空");

        // 检查是否含有非法文件名字符
        var invalidChars = Path.GetInvalidFileNameChars();
        string fileName = Path.GetFileName(path);
        if (fileName.Any(c => invalidChars.Contains(c)))
        {
            throw new ArgumentException($"文件路径 '{path}' 包含非法字符");
        }

        // 替换分隔符
        path = path.Replace('\\', '/');

        // 组合并获取绝对路径
        var fullPath = Path.GetFullPath(Path.Combine(root, path));

        // 防止越界访问
        if (!fullPath.StartsWith(root, StringComparison.OrdinalIgnoreCase))
        {
            throw new ArgumentException($"文件路径 '{path}' 越界访问!");
        }

        return fullPath;
    }
}

View on GitHub (pinned to a7cb36712d)

Solutions

1. Sanitize the path at the source: strip or replace invalid chars before calling NormalizePath.
2. If the path is user-supplied, validate against a whitelist pattern (e.g., ^[A-Za-z0-9._/-]+$) and reject early with a clear message.
3. Note GetFileName returns the whole path if no separator is present — for directory-like inputs ensure the check targets the intended segment.

Example fix

// before
var invalidChars = Path.GetInvalidFileNameChars();
string fileName = Path.GetFileName(path);
if (fileName.Any(c => invalidChars.Contains(c)))
    throw new ArgumentException($"文件路径 '{path}' 包含非法字符");

// after (name the offending chars)
var invalidChars = Path.GetInvalidFileNameChars();
string fileName = Path.GetFileName(path);
var found = fileName.Where(c => invalidChars.Contains(c)).Distinct().ToArray();
if (found.Length > 0)
    throw new ArgumentException(
        $"文件路径 '{path}' 包含非法字符: {string.Join(", ", found.Select(c => $"'{c}'"))}", nameof(path));

// Whitelist filenames from untrusted sources
if (!System.Text.RegularExpressions.Regex.IsMatch(fileName, @"^[A-Za-z0-9._-]+(\.[A-Za-z0-9]+)?$"))
    throw new ArgumentException($"文件名包含非法字符: {fileName}");

static bool HasNoInvalidChars(string fileName)
{
    var invalid = Path.GetInvalidFileNameChars();
    return !fileName.Any(c => invalid.Contains(c));
}

catch (ArgumentException ex) when (ex.Message.Contains("非法字符"))
{
    Toast.Error($"文件名非法: {ex.Message}");
}

When it happens

Trigger: NormalizePath receives a path whose final segment (Path.GetFileName) includes an OS-invalid char. Examples: 'scripts/foo<bar.js', 'a/b:c.js' on Windows (colon), 'x/y|z.txt'. The invalidChars set is platform-specific (Windows is stricter than Linux).

Common situations: A manifest or webview request supplies a path with shell-special or reserved characters; cross-platform mismatch (a path valid on Linux fails on Windows where ':' and others are illegal); user-typed filename with stray punctuation.

Related errors

• 文件路径不能为空
• 文件路径 '{path}' 越界访问!
• 要启动的程序不存在。
• 仓库中不存在路径: {sourcePath}
• 当前选择的自动战斗策略文件不存在

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/308245853cfe6a24. Report an issue: GitHub.