Common development environment issues and solutions

During the development process with uni-app, developers often encounter various environmental issues that may involve multiple stages such as compilation, runtime, and debugging. From dependency installation to platform compatibility and performance optimization, each stage can become a stumbling block. Below are the specific manifestations and solutions for common problems.

Dependency Installation Failures

Dependency installation failures are usually caused by network issues or version conflicts. When errors like ECONNRESET or ETIMEDOUT occur during npm or yarn installation, try switching the mirror source:

# Switch to Taobao mirror
npm config set registry https://registry.npmmirror.com
# Clear cache and retry
npm cache clean --force

If a peer dependency conflict arises, manually specify the version. For example, when sass-loader and node-sass versions are incompatible:

// package.json
{
  "devDependencies": {
    "sass-loader": "^10.1.1",
    "node-sass": "^6.0.1"
  }
}

HBuilderX Toolchain Issues

The built-in compiler in HBuilderX may malfunction. For example, if a "module not bound" error appears during real-device debugging, check the following:

1. Project Root Directory: Ensure it correctly includes manifest.json.
2. Custom Component Paths: Use absolute paths:

// Incorrect example
import comp from '../../components/comp.vue'
// Correct example
import comp from '@/components/comp.vue'

3. Reinstall Compiler Plugins: Go to Menu → Tools → Plugin Installation → Reinstall scss/sass compilation.

Platform-Specific Style Failures

When adapting to multiple platforms, styles may behave differently on iOS and Android. For example, to handle the bottom safe area, use conditional compilation:

/* General style */
.page {
  padding-bottom: 20px;
}
/* iOS-specific adaptation */
/* #ifdef MP-WEIXIN || APP-PLUS */
.page {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
}
/* #endif */

Hot Reload Failure

Code changes may not trigger automatic refreshes during development. Possible causes include:

1. File Watch Limit: The project path is too deep, exceeding Node.js file watch limits.

# Solution: Increase system watch limits
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2. Custom Loader Conflict: Check if vue.config.js incorrectly overrides configurations.

// Incorrect configuration example
chainWebpack(config) {
  config.module.rule('vue').use('vue-loader').clear()
}

White Screen During Real-Device Debugging

For a white screen on Android real-device debugging, troubleshoot step-by-step:

1. Base Library Version: Ensure the mobile WeChat version is >7.0.6.
2. vConsole Debugging: Force debugging in main.js.

// Force debugging in development environment
if (process.env.NODE_ENV === 'development') {
  uni.setEnableDebug({ enableDebug: true })
}

3. Resource Path Issues: Check if static resources use online URLs or correct relative paths.

Subpackage Loading Failure in Mini Programs

When subpackages exceed the 2MB limit, optimize the strategy:

1. Main Package Slimming: Move non-first-screen resources to subpackages.

// pages.json configuration example
{
  "subPackages": [{
    "root": "subpackage",
    "pages": [{
      "path": "detail",
      "style": { "navigationBarTitleText": "Details Page" }
    }]
  }]
}

2. Image Compression: Use tools like TinyPNG for batch compression.
3. On-Demand Component Loading: Dynamically load subpackage components.

// Dynamically load subpackage components
const comp = () => import('@/subpackage/components/heavy-comp.vue')

Cross-Platform API Compatibility Issues

The same API may behave differently across platforms. For example, uni.getSystemInfo returns varying structures:

// Unified handling solution
function getSafeArea() {
  const systemInfo = uni.getSystemInfoSync()
  return {
    top: systemInfo.statusBarHeight || 0,
    bottom: systemInfo.screenHeight - systemInfo.windowHeight - (systemInfo.statusBarHeight || 0)
  }
}

Custom Component Rendering Issues

Recursive or dynamic components may cause rendering problems. For example, infinite recursion in tree components:

<template>
  <view v-for="item in treeData">
    <tree-node :data="item" v-if="item.children"/>
  </view>
</template>

<script>
export default {
  name: 'tree-node', // Must declare the name property
  props: ['data']
}
</script>

Native Plugin Integration Errors

When using uni-native plugins, Android may report Uncaught TypeError:

1. Check Plugin Permissions: Ensure AndroidManifest.xml includes required permissions.
2. Synchronize Plugin Versions: Ensure HBuilderX version matches the plugin SDK version.
3. Regenerate Signatures: Delete unpackage/debug/android_debug.keystore and rerun.

Performance Optimization Practices

Solutions for laggy list pages:

1. Virtual List Technique: Use <scroll-view> + v-for with useVirtualList.

<scroll-view 
  scroll-y 
  :scroll-top="virtualScrollTop"
  @scroll="handleScroll">
  <view 
    v-for="item in visibleData"
    :key="item.id"
    :style="{ height: itemHeight + 'px' }">
    {{ item.content }}
  </view>
</scroll-view>

2. Image Lazy Loading: Configure uni.lazyLoad.

<image lazy-load :src="imgUrl" mode="aspectFill"></image>

Cloud Packaging Exception Handling

Common error codes and solutions for cloud packaging failures:

• Error 30004: Incorrect certificate password; check keystore password.
• Error 20003: Package name conflict; modify id in manifest.json.
• Error 10012: Icon size mismatch; ensure a 192x192 PNG icon exists.

Breaking Local Storage Limits

When uni.setStorage exceeds the 10MB limit:

1. Chunked Storage: Split large data into multiple keys.

function setBigData(key, data) {
  const chunkSize = 1024 * 1024 // 1MB chunks
  const total = Math.ceil(data.length / chunkSize)
  uni.setStorageSync(`${key}_total`, total)
  for(let i=0; i<total; i++) {
    uni.setStorageSync(`${key}_${i}`, data.slice(i*chunkSize, (i+1)*chunkSize))
  }
}

2. File System API: Use uni.saveFile to store in the document directory.

Resolving Third-Party Library Conflicts

Style conflicts when introducing multiple UI libraries (e.g., vant and uView):

1. Scope Isolation: Add style prefixes.

// vite.config.js
css: {
  preprocessorOptions: {
    scss: {
      additionalData: `$namespace: 'custom-';`
    }
  }
}

2. On-Demand Loading: Optimize with babel-plugin-import.

// babel.config.js
plugins: [
  ['import', {
    libraryName: 'vant',
    customName: name => `vant/lib/${name}`,
    style: name => `vant/lib/${name}/style`
  }]
]

Continuous Integration Adaptation

Special configurations for Jenkins automated builds:

1. Environment Variable Injection: Distinguish environments via .env files.

# .env.production
VUE_APP_API_BASE=https://api.example.com
NODE_ENV=production

2. Build Cache Strategy: Cache node_modules to speed up builds.

// Jenkinsfile
stage('Install') {
  steps {
    sh 'npm install'
    stash includes: 'node_modules/', name: 'node_modules'
  }
}