本文详解 Tampermonkey 脚本“控制台能运行、脚本却无效”的典型原因，重点解决因 DOM 加载时机不一致导致的元素查询失败问题，并提供 setTimeout 快速验证方案及更健壮的 MutationObserver 生产级替代方案。
本文详解 tampermonkey 脚本“控制台能运行、脚本却无效”的典型原因，重点解决因 dom 加载时机不一致导致的元素查询失败问题，并提供 `settimeout` 快速验证方案及更健壮的 `mutationobserver` 生产级替代方案。
在开发 Tampermonkey 用户脚本时，一个高频困惑是：同一段 JavaScript 代码在 Chrome 开发者工具控制台中执行成功（按钮正常添加），但封装为用户脚本后却完全无响应。这并非代码逻辑错误，而往往源于执行环境与生命周期的根本差异——控制台总是在页面完全加载、DOM 稳定后手动执行；而 Tampermonkey 默认的 @run-at document-body 仅保证 <body> 存在，不保证目标节点（如动态渲染的表单区域）已挂载完成。
你的脚本中关键问题就出在这里：
const notes = document.querySelector("#create-form > div > div.box-body > div > div:nth-child(10) > div");该选择器依赖一个深层嵌套、极可能由前端框架（如 Vue/React）或异步 JS 动态生成的结构。当 Tampermonkey 在 document-body 阶段执行时，#create-form 往往尚未渲染，querySelector() 返回 null，后续 appendChild() 报错（静默失败或控制台报错），导致按钮从未创建。
✅ 快速验证：使用 setTimeout 延迟执行
最直接的调试手段是加入可控延迟，确认是否为时机问题：
// ==UserScript==
// @name SNIPEIT OFFICE BUTTONS
// @namespace http://tampermonkey.net/
// @version 0.2
// @description Add Office 2013/2019 buttons to Snipe-IT asset form
// @author You
// @match https://your-snipeit-domain.com/* // ← 替换为实际 URL
// @grant none
// @run-at document-body
// ==/UserScript==
(function() {
'use strict';
const myDelay = 2000; // 初始设为2秒，成功后逐步降低至最小稳定值（如300ms）
setTimeout(() => {
const notes = document.querySelector("#create-form > div > div.box-body > div > div:nth-child(10) > div");
if (!notes) {
console.warn('⚠️ Target container not found. Check selector or increase delay.');
return;
}
// 创建 Office 2013 按钮
const btn2013 = document.createElement('button');
btn2013.textContent = 'Office 2013 TM';
btn2013.style.marginRight = '8px'; // 提升可读性
btn2013.addEventListener('click', () => alert('Office 2013 selected!'));
notes.appendChild(btn2013);
// 创建 Office 2019 按钮
const btn2019 = document.createElement('button');
btn2019.textContent = 'Office 2019 TM';
btn2019.addEventListener('click', () => alert('Office 2019 selected!'));
notes.appendChild(btn2019);
}, myDelay);
})();? 调试提示：打开浏览器控制台（F12 → Console），刷新页面。若看到 ⚠️ Target container not found...，说明选择器失效；若按钮出现，则证实是 DOM 时机问题。逐步减小 myDelay 值（如 500, 300），找到最低可靠延迟。
⚠️ 注意事项与最佳实践
- 避免硬编码长 CSS 选择器：div:nth-child(10) 极易因 UI 更新断裂。优先使用语义化 ID 或 class（如 class="office-button-container"）。
- 始终校验节点存在性：if (!notes) return; 防止脚本崩溃。
- *@grant none 下禁止使用 `GM_` API**：当前配置正确，无需额外权限。
- 不要滥用 setTimeout：延迟方案仅用于验证和临时修复，长期使用会导致不可靠（网络波动、设备性能差异影响稳定性）。
✅ 推荐方案：使用 MutationObserver 监听 DOM 变化（生产级）
真正健壮的解法是监听目标父容器的插入事件，一旦 #create-form 出现即刻执行：
// ==UserScript==
// @name SNIPEIT OFFICE BUTTONS (Observer)
// @namespace http://tampermonkey.net/
// @version 0.3
// @description Robustly inject Office buttons using MutationObserver
// @author You
// @match https://your-snipeit-domain.com/*
// @grant none
// @run-at document-idle // 更优：等页面空闲时启动
// ==/UserScript==
(function() {
'use strict';
function injectButtons() {
const notes = document.querySelector("#create-form > div > div.box-body > div > div:nth-child(10) > div");
if (!notes) return;
const btn2013 = document.createElement('button');
btn2013.textContent = 'Office 2013 TM';
btn2013.addEventListener('click', () => alert('Office 2013 selected!'));
notes.appendChild(btn2013);
const btn2019 = document.createElement('button');
btn2019.textContent = 'Office 2019 TM';
btn2019.addEventListener('click', () => alert('Office 2019 selected!'));
notes.appendChild(btn2019);
console.log('✅ Office buttons injected successfully.');
}
// 创建观察器，监听 body 下新增的 #create-form 元素
const observer = new MutationObserver((mutations) => {
mutations.forEach(mutation => {
mutation.addedNodes.forEach(node => {
if (node.nodeType === 1 && node.querySelector('#create-form')) {
injectButtons();
observer.disconnect(); // 任务完成，停止监听
}
});
});
});
// 开始观察整个 document.body 的子节点变化
observer.observe(document.body, { childList: true, subtree: true });
})();此方案优势显著：
- 零延迟：目标节点一出现立即注入，不依赖猜测性等待；
- 高可靠性：不受网络、渲染速度影响；
- 资源友好：任务完成后自动断开，无内存泄漏风险。
总结
控制台有效而 Tampermonkey 失效，本质是执行时序与 DOM 生命周期的错位。优先用 setTimeout 快速定位问题，再用 MutationObserver 彻底解决。同时优化选择器鲁棒性、增加存在性检查，你的用户脚本将从“偶尔工作”升级为“始终可靠”。
