《原神》Web端JS脚本常见报错与调试方法

在开发或使用针对《原神》Web端（如米游社网页版、签到福利页面、版本前瞻网页活动以及祈愿记录导出工具）的JavaScript用户脚本（如Tampermonkey脚本或浏览器控制台小工具）时，许多开发者会频繁遭遇网络请求被阻断、页面元素找不到以及鉴权失效等报错。本文将系统梳理这些典型报错的具体原因，并结合现代浏览器开发工具（DevTools）给出针对性的调试步骤与代码级解决方案。

一、原神Web端运行环境与脚本执行链路

《原神》官方Web产品大多基于现代前端单页应用（SPA）框架（如Vue或React）构建，普遍具备复杂的动态渲染机制、严格的跨域限制（CORS）与Content Security Policy（CSP）防护策略。此外，官方API服务通常部署在独立子域（如 api-takumi.mihoyo.com 或 hk4e-api.mihoyo.com），且要求特定的校验签名（DS动态密钥）与Cookie鉴权凭证。

理解用户脚本在浏览器中的运行上下文是排查一切异常的前提。直接在DevTools控制台运行的代码与在Tampermonkey沙箱中运行的脚本存在显著差异：前者严格受宿主页面同源策略约束，而后者可通过特权API绕过跨域限制。

二、常见报错一：跨域拦截（CORS）与网络请求阻断

在开发查询角色展柜、祈愿流水或签到状态的脚本时，最常遇到的第一道坎是控制台红色的网络错误：

Access to fetch at 'https://api-takumi.mihoyo.com/...' from origin 'https://ys.mihoyo.com' 
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

1. 成因分析

现代浏览器强制执行同源策略（Same-Origin Policy）。当用户在活动页面（例如 https://act.mihoyo.com/...）通过原生 window.fetch 或 XMLHttpRequest 发起请求至 api-takumi.mihoyo.com 时，浏览器会检查目标服务器返回的响应头是否包含匹配当前源的 Access-Control-Allow-Origin。由于官方API并不对所有子域开放通用跨域读写权限，原生网络调用会被浏览器直接阻断并抛出异常。

2. 解决方案：借助用户脚本特权API

如果使用油猴插件（Tampermonkey / Violentmonkey），严禁直接使用原生 fetch。应当在元数据中声明 @grant GM_xmlhttpRequest 与 @connect 授权域名，由扩展进程代理发出跨域请求：

// ==UserScript==
// @name         原神Web数据请求工具
// @namespace    https://example.com/genshin-tool
// @version      1.0.0
// @match        https://act.mihoyo.com/*
// @match        https://www.miyoushe.com/ys/*
// @grant        GM_xmlhttpRequest
// @connect      api-takumi.mihoyo.com
// @connect      hk4e-api.mihoyo.com
// ==/UserScript==

function safeApiRequest(url) {
    return new Promise((resolve, reject) => {
        GM_xmlhttpRequest({
            method: 'GET',
            url: url,
            headers: {
                'Accept': 'application/json, text/plain, */*',
                'x-rpc-client_type': '5', // 5 代表 Web 端
                'x-rpc-app_version': '2.40.1'
            },
            onload: function(response) {
                if (response.status >= 200 && response.status < 300) {
                    try {
                        const json = JSON.parse(response.responseText);
                        resolve(json);
                    } catch (e) {
                        reject(new Error('JSON解析失败: ' + e.message));
                    }
                } else {
                    reject(new Error(`HTTP错误: ${response.status}`));
                }
            },
            onerror: function(err) {
                reject(err);
            }
        });
    });
}

三、常见报错二：DOM异步渲染导致的空指针异常（TypeError）

另一个极高频的报错发生在操作页面按钮或抓取签到状态时：

Uncaught TypeError: Cannot read properties of null (reading 'querySelector')
或
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

1. 成因分析

《原神》网页活动与米游社页面是重度依赖客户端渲染的单页架构。当脚本执行时，页面 HTML 骨架可能仅包含一个空的 <div id="app"></div>，核心内容面板需要等待前置接口返回后才动态挂载到 DOM 树中。如果脚本配置了 @run-at document-end 并立即执行 document.querySelector('.sign-btn')，此时元素根本尚未生成，直接调用方法必然触发空指针异常。

2. 解决方案：基于 MutationObserver 的异步等待机制

不建议使用脆弱的固定延时（如 setTimeout(fn, 3000)），因网络波动极易导致时序失效。推荐使用 MutationObserver 封装一个精准的元素挂载监听器：

/**
 * 异步监听指定选择器的DOM节点生成
 * @param {string} selector CSS选择器
 * @param {number} timeout 超时时间(毫秒)
 * @returns {Promise<Element>}
 */
function waitForElement(selector, timeout = 10000) {
    return new Promise((resolve, reject) => {
        const existing = document.querySelector(selector);
        if (existing) {
            return resolve(existing);
        }

        const timer = setTimeout(() => {
            observer.disconnect();
            reject(new Error(`查找元素 [${selector}] 超时 (${timeout}ms)`));
        }, timeout);

        const observer = new MutationObserver(() => {
            const el = document.querySelector(selector);
            if (el) {
                clearTimeout(timer);
                observer.disconnect();
                resolve(el);
            }
        });

        observer.observe(document.body, {
            childList: true,
            subtree: true
        });
    });
}

// 实际使用示例：安全绑定点击事件
(async function() {
    try {
        const checkinButton = await waitForElement('.bbs-sign-btn, .act-sign__btn');
        console.log('目标签到节点加载就绪:', checkinButton);
        checkinButton.addEventListener('click', () => {
            console.log('触发点击操作');
        });
    } catch (err) {
        console.error('元素等待异常:', err.message);
    }
})();

此外，若原神网页活动嵌套在多层 <iframe> 容器中，直接在顶层窗口的 document.querySelector 将无法穿透异源 iframe。需要配置脚本匹配具体的 iframe URL（如 https://webstatic.mihoyo.com/*），确保脚本直接注入到目标子帧中运行。

四、常见报错三：接口鉴权与业务错误码（retcode != 0）

在网络请求正常发出且状态码为 200 的情况下，米哈游 API 通常在响应体 JSON 中返回 retcode 字段。常见的非零报错及对应机制如下：

五、常见报错四：CSP策略拦截与环境隔离限制

在米哈游特定活动页面执行控制台脚本时，有时会直接收到拒绝载入外部脚本的报错：

Refused to load the script 'https://cdn.example.com/lib.js' because it violates the following Content Security Policy directive: "script-src 'self' 'unsafe-eval' https://*.mihoyo.com".

1. 成因分析

为防止 XSS 注入与挂马，官方网站配置了严格的 CSP 策略。若脚本试图动态在 DOM 树中插入未经白名单认证的第三方 CDN 脚本（例如 document.body.appendChild(scriptTag)），浏览器引擎会在载入前直接阻断。

2. 解决方案

• 使用 @require 预打包： 在 Tampermonkey 脚本中，第三方依赖库（如 jQuery、CryptoJS、Dayjs）应当直接在脚本头部通过 // @require https://cdn.jsdelivr.net/... 载入。油猴管理器会在扩展沙箱环境预先下载并注入该库，绕过宿主页面的 CSP 脚本源限制。
• 规避 eval() 与内联注入： 严禁使用 new Function(code) 或 eval() 执行动态代码，尽量采用标准 ES6 模块化或原生对象操作。

六、四类核心报错对比与对应修复机制

为了让排查过程更加直观，下表梳理了原神Web脚本四大常见报错的表象特征、关键成因与代码修复策略对照：

七、高效实战调试技巧：DevTools 进阶配置

在面对复杂偶发性报错时，单纯依靠 console.log 效率极低。建议充分利用现代浏览器 DevTools 的高级调试能力：

1. 捕获未处理异常并自动断点（Pause on uncaught exceptions）

按 F12 打开控制台，切换至 Sources (源代码) 面板。点击右上角的暂停图标（或勾选 Pause on exceptions 并选中 Pause on caught exceptions）。当用户脚本发生任何无法读取属性或语法错误时，浏览器会立即冻结当前 JS 线程，并在报错代码行停留。此时可以在 Scope (作用域) 面板中审查当前函数的全部局部变量与 DOM 节点引用。

2. XHR/fetch 断点监控特定接口

在 Sources 面板右侧栏中找到 XHR/fetch Breakpoints，点击 + 添加过滤关键词（例如 api-takumi 或 hk4e）。只要网页或脚本触发匹配该 URL 的网络请求，浏览器会在请求发送前瞬间自动中断。通过调用栈（Call Stack），你可以精确看到是哪一段代码在何时构造了参数，并能核验即将发出的 Headers 与 Payload 是否完备。

3. 油猴脚本内置日志与持久化调试

建议在脚本开发阶段统一封装日志输出函数，并在生产环境中支持按需开启调试日志：

const DEBUG = true;

function debugLog(module, ...args) {
    if (!DEBUG) return;
    const timestamp = new Date().toISOString().substring(11, 23);
    console.log(`%c[原神脚本调试][${timestamp}][${module}]`, 'color: #52677D; font-weight: bold;', ...args);
}

// 记录结构化调试日志
debugLog('Auth', '正在读取本地身份凭证...');
debugLog('Network', '发起祈愿数据同步请求:', { page: 1, size: 20 });

八、全流程排查决策树与验证闭环

在遭遇报错时，建议按照以下决策树进行系统化诊断，逐层剥离干扰项，快速定位问题根源：

九、总结与安全合规建议

调试《原神》Web端JS脚本的本质，是在现代浏览器的严苛安全上下文（同源策略、CSP、异步生命周期）与米哈游官方反刷风控机制之间建立合规、健壮的通信链路。在日常开发与维护中，遵循以下三条准则可规避绝大部分问题：

1. 尊重生命周期： 坚决杜绝硬编码 setTimeout，全面采用 MutationObserver 监听动态组件挂载。
2. 规范请求通道： 用户脚本跨域请求必须依赖 GM_xmlhttpRequest 并完整声明 @connect 权限，严禁直接在宿主页面强制注入无权限的 Fetch 调用。
3. 克制请求节奏： 严格限制自动化脚本的发包频次，避免在短时间内突发高并发请求，不仅保护个人账号免遭风控滑块拦截，也减少对公共服务基础设施的不必要负担。