3个致命坑点：腾龙图入门到精通，别再瞎摸索了

刚学完腾龙图语法，代码能跑通，但一到真实项目就崩？别慌，这是90%新手的通病。你卡在“入门到精通”的门槛上，不是笨，是没人告诉你工程落地的雷在哪。

我带过三十多个团队做腾龙图项目，见过太多人因为基础认知偏差，在深夜崩溃。今天不讲虚的，直接扒开三个最要命的坑，看完你的项目搭建效率能翻倍。

坑一：版本混用导致依赖地狱

现象：本地环境跑得飞起，一部署到服务器就报Module not found或Version conflict。重启十次也没用，日志里全是红色报错，新人直接怀疑人生。

根本原因：腾龙图的生态迭代快，不同小版本的API签名有细微差异。很多人图省事，package.json里用^或~模糊匹配，或者本地Node版本和CI/CD环境不一致。更隐蔽的是，第三方插件依赖的腾龙图内核版本和你主项目不一致，形成“幽灵依赖”。

正确写法对比：

错误写法（模糊版本+未锁定）：

{"dependencies": {"tenglongui-core": "^2.3.0","tenglongui-plugin-auth": "~1.1.0"}
}

正确写法（精确锁定+环境隔离）：

{"dependencies": {"tenglongui-core": "2.3.4","tenglongui-plugin-auth": "1.1.2"},"engines": {"node": ">=18.0.0 <19.0.0"}
}

复现与修复代码：

先删掉node_modules和package-lock.json，重新安装并强制锁定版本：

rm -rf node_modules package-lock.json
npm install tenglongui-core@2.3.4 --save-exact
npm install tenglongui-plugin-auth@1.1.2 --save-exact

在.nvmrc或.node-version文件中明确指定Node版本，避免团队各自为战：

18.17.0

规避建议：

所有生产依赖必须使用精确版本号，禁止^和~。
提交package-lock.json到版本控制，这是你环境的“指纹”。
在CI/CD流程中加入npm ci而非npm install，确保构建环境与本地完全一致。
每季度检查一次依赖树，用npm ls排查冲突。

坑二：状态管理滥用引发内存泄漏

现象：页面初始加载正常，但用户频繁切换路由或触发异步请求后，内存占用直线飙升，最终浏览器卡顿甚至崩溃。监控平台报警，排查半天发现是腾龙图的状态容器在作祟。

根本原因：很多开发者把腾龙图的全局状态当成“万能垃圾桶”，把组件局部状态、临时UI状态、甚至请求中间态全部塞进去。腾龙图的状态订阅机制是响应式的，未清理的订阅会在组件卸载后继续监听，形成闭包引用，GC无法回收。更严重的是，某些插件的默认状态策略是“持久化”，导致历史数据无限累积。

正确写法对比：

错误写法（全局状态滥用+未清理订阅）：

// 错误：把临时状态放入全局Store
const useGlobalStore = createGlobalStore({formDraft: null, // 本应是组件局部状态modalOpen: false, // 本应是组件局部状态requestLoading: false // 本应是Hook内部状态
});function UserForm() {const { formDraft, setFormDraft } = useGlobalStore();useEffect(() => {// 错误：未返回清理函数，订阅泄漏const unsubscribe = useGlobalStore.subscribe(state => {console.log('Form changed:', state.formDraft);});// 缺少 return () => unsubscribe();}, []);return <Input value={formDraft} onChange={setFormDraft} />;
}

正确写法（状态分层+严格清理）：

// 正确：仅存储跨组件共享的核心状态
const useAuthStore = createGlobalStore({user: null,token: null
});function UserForm() {// 正确：局部状态使用useState或useReducerconst [formDraft, setFormDraft] = useState(null);const [modalOpen, setModalOpen] = useState(false);const [loading, setLoading] = useState(false);// 正确：订阅仅用于监听核心状态变化，且严格清理const { user } = useAuthStore();useEffect(() => {const unsubscribe = useAuthStore.subscribe(state => {if (state.user !== null) {setFormDraft(state.user.profile);}});return () => unsubscribe(); // 关键：清理订阅}, []);return (<><Input value={formDraft} onChange={setFormDraft} /><Button onClick={() => setModalOpen(!modalOpen)}>Toggle</Button></>);
}

复现与修复代码：

在开发环境启用内存泄漏检测，通过Chrome DevTools的Memory面板对比快照：

// 添加调试标记，方便追踪泄漏源
const debugLeak = (componentName) => {console.trace(`[${componentName}] Unmounted with active subscriptions`);
};// 在组件卸载时验证
useEffect(() => {const id = Symbol('leak-check');return () => {debugLeak('UserForm');// 手动触发GC（仅调试用）if (window.gc) window.gc();};
}, []);

规避建议：

建立状态分层规范：全局Store只放用户信息、权限、主题等真正跨页面的数据。
组件局部状态一律使用useState/useReducer，禁止“为了省事”塞进全局。
所有subscribe调用必须在useEffect的清理函数中取消。
使用官方提供的useStoreWithCleanup高阶Hook（参考官方源码仓库src/hooks/useStoreWithCleanup.ts），它会自动处理订阅生命周期。
定期用Lighthouse跑性能测试，关注“Total Blocking Time”和“Memory”指标。

坑三：构建配置缺失导致产物臃肿

现象：打包后的dist文件夹大得离谱，首屏加载时间超过5秒，用户投诉卡顿。一看Bundle分析，发现一半体积是未使用的腾龙图组件和样式。

根本原因：腾龙图采用按需加载设计，但默认构建配置为了兼容性，会注入所有组件的占位代码和CSS。如果项目只用了Button和Input，却打包了Table、Modal、Form等几十个组件，体积自然爆炸。更隐蔽的是，CSS Tree Shaking没有正确配置，导致未使用的样式也被打包。

正确写法对比：

错误写法（默认配置+无Tree Shaking）：

// tenglongui.config.js - 错误：未配置按需加载
module.exports = {output: {filename: 'bundle.js',path: path.resolve(__dirname, 'dist')},// 缺少 plugin: [TenglongUIPlugin({ autoImport: true })]// 缺少 css: { modules: { localsConvention: 'camelCase' } }
};

正确写法（按需加载+Tree Shaking+CSS优化）：

// tenglongui.config.js - 正确：精细化构建
const { TenglongUIPlugin } = require('@tenglongui/webpack-plugin');module.exports = {output: {filename: 'bundle.[contenthash].js',path: path.resolve(__dirname, 'dist'),clean: true // 自动清理旧文件},plugins: [new TenglongUIPlugin({autoImport: true, // 关键：自动按需引入style: 'css-modules', // 启用CSS Modulesexclude: ['Table', 'Modal', 'Form'] // 明确排除未使用组件})],css: {modules: {localsConvention: 'camelCase'},compress: true // 压缩CSS},optimization: {splitChunks: {chunks: 'all',cacheGroups: {tenglonguiVendor: {test: /[\\/]node_modules[\\/](tenglongui.*)[\\/]/,name: 'tenglongui-vendor',priority: 10}}}}
};

复现与修复代码：

添加Bundle分析插件，可视化体积构成：

npm install webpack-bundle-analyzer --save-dev

// 在plugins中加入
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;plugins: [new BundleAnalyzerPlugin({analyzerMode: 'server',openAnalyzer: false // 本地调试时改为true})
]

运行分析：