Compilation errors and debugging techniques

Common Types of Compilation Errors

The compilation errors encountered during uni-app development can be primarily categorized into the following types:

Syntax errors are the most common compilation issues. For example, using incorrect tag closing methods in templates:

<view>This is an unclosed tag

Or using non-standard JavaScript syntax in scripts:

const a = 1
const b = 2
console.log(a, b

These errors usually come with clear error messages indicating the location and type of the error.

Dependency-related errors are also common. For instance, forgetting to install required npm packages:

[Warning] Cannot find module: 'lodash'

Or configuring non-existent plugins in manifest.json:

{
  "plugins": {
    "non-existent-plugin": {}
  }
}

Debugging Tool Techniques

Chrome Developer Tools are a powerful ally for debugging uni-app. When running on the H5 side, you can use them directly:

1. Press F12 to open Developer Tools.
2. Switch to the Sources panel to view the source code.
3. Use the Console panel to check log output.

For debugging on mini-program platforms, you can use the developer tools provided by each platform:

• WeChat Developer Tools
• Alipay Mini Program Developer Tools
• Baidu Developer Tools

For real-device debugging, the adb tool is particularly useful:

adb logcat | grep "uni-app"

Runtime Error Troubleshooting Methods

When encountering a blank screen, follow these steps to troubleshoot:

1. Check if the page path is correct.
2. Look for errors in the console.
3. Verify if the page components are properly defined.

Data binding failures are common issues, such as:

<view>{{ message }}</view>

export default {
  data() {
    return {
      // Forgot to define message
    }
  }
}

Undefined event handler errors:

<button @click="handleClick">Click</button>

export default {
  methods: {
    // Forgot to define the handleClick method
  }
}

Performance-Related Errors

Long list rendering performance issues can be optimized with virtual-list:

<uni-list>
  <uni-list-item v-for="item in longList" :key="item.id">
    {{ item.name }}
  </uni-list-item>
</uni-list>

Image loading performance issues:

<!-- Bad practice -->
<img :src="item.image" v-for="item in list">

<!-- Optimized approach -->
<img :src="item.image" v-for="item in list" lazy-load>

Platform-Specific Errors

APIs vary across mini-program platforms. For example, getting system information:

// WeChat Mini Program
wx.getSystemInfo({})

// Alipay Mini Program
my.getSystemInfo({})

// Unified uni-app approach
uni.getSystemInfo({})

CSS style differences also require special attention:

/* Styles that work on H5 but may fail on mini-programs */
.div {
  position: fixed;
  bottom: 0;
}

/* Cross-platform compatible approach */
.uni-fixed-bottom {
  position: fixed;
  bottom: 0;
}

Common Custom Component Issues

Component props validation failures:

export default {
  props: {
    count: {
      type: Number,
      required: true
    }
  }
}

If the wrong type is passed during usage:

<my-component count="10"></my-component>

Slot misuse errors:

<!-- Parent component -->
<child-component>
  <view>Default slot content</view>
</child-component>

<!-- Child component -->
<view>
  <slot></slot>
</view>

Third-Party Plugin Integration Issues

Common errors when importing UI libraries:

// Incorrect example: Component not properly registered
import { uniButton } from '@dcloudio/uni-ui'

// Correct usage
import uniButton from '@dcloudio/uni-ui/lib/uni-button/uni-button.vue'

npm package version conflicts:

npm ls package-name

This command can help identify conflicting versions in the dependency tree.

Packaging and Publishing Issues

Subpackage loading configuration errors:

{
  "subPackages": [
    {
      "root": "pages/sub",
      "pages": [
        "index/index"
      ]
    }
  ]
}

Incorrect path configurations can cause subpackage loading failures.

Environment Configuration Issues

Node version incompatibility:

nvm use 14

It's recommended to use LTS versions of Node.js for development.

Code Quality Tool Usage

ESLint can help identify potential issues:

// .eslintrc.js
module.exports = {
  rules: {
    'no-unused-vars': 'warn'
  }
}

Prettier formatting inconsistencies:

{
  "semi": false,
  "singleQuote": true
}

Network Request Debugging

Cross-origin issue solutions:

// manifest.json
{
  "h5": {
    "devServer": {
      "proxy": {
        "/api": {
          "target": "http://backend.example.com",
          "changeOrigin": true
        }
      }
    }
  }
}

Request timeout handling:

uni.request({
  url: 'https://example.com/api',
  timeout: 5000,
  success() {},
  fail(err) {
    console.error('Request failed:', err)
  }
})

State Management Errors

Vuex misuse:

// Incorrect example: Directly modifying state
this.$store.state.count = 10

// Correct approach
this.$store.commit('increment')

Unregistered modules:

// store/index.js
import moduleA from './moduleA'

export default new Vuex.Store({
  modules: {
    moduleA // Forgetting to register will cause access failures
  }
})

Lifecycle Hook Issues

Differences between created and mounted:

export default {
  created() {
    // DOM not mounted, cannot manipulate DOM
  },
  mounted() {
    // Safe to manipulate DOM
  }
}

Asynchronous data loading timing:

export default {
  async mounted() {
    try {
      this.data = await this.fetchData()
    } catch (error) {
      console.error('Data loading failed:', error)
    }
  }
}

Style Scoping Issues

Scoped styles not working:

<style scoped>
/* Deep selector */
::v-deep .external-class {
  color: red;
}
</style>

Global style pollution:

<style>
/* Affects all pages */
body {
  margin: 0;
}
</style>

Routing and Navigation Issues

Page navigation parameter errors:

// Incorrect example: Directly passing objects
uni.navigateTo({
  url: '/pages/detail?id=' + JSON.stringify(obj)
})

// Correct approach: Pass primitive types
uni.navigateTo({
  url: '/pages/detail?id=' + obj.id
})

Route guard usage:

// main.js
uni.addInterceptor('navigateTo', {
  invoke(args) {
    if (!isLogin()) {
      uni.redirectTo({ url: '/pages/login' })
      return false
    }
    return true
  }
})

Native Plugin Compatibility Issues

Camera plugin usage example:

uni.chooseImage({
  count: 1,
  success(res) {
    const tempFilePaths = res.tempFilePaths
    uni.previewImage({
      urls: tempFilePaths
    })
  }
})

Missing permission configurations:

// manifest.json
{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>"
        ]
      }
    }
  }
}