miniprogram-to-uniapp 项目使用指南

miniprogram-to-uniapp 是一个功能强大的开源工具，专门用于将各种小程序项目（包括微信、QQ、头条/抖音、支付宝/钉钉和百度等平台的小程序）转换为 uni-app 项目。通过这个工具，开发者可以轻松实现一次编写，多平台发布的目标。

项目概述

该项目基于 Node.js 开发，当前版本支持 Node.js v18.19.0。核心转换逻辑依赖于 GoGoCode 代码转换工具库，能够高效处理小程序的语法结构和组件体系，将其转换为符合 uni-app 框架规范的代码。

安装方式

Npm 全局安装

npm install miniprogram-to-uniapp -g

安装完成后，系统会添加 wtu 命令行工具，可用于执行转换操作。

HBuilderX 插件安装

除了命令行方式，还可以通过 HBuilderX 插件市场安装对应的插件版本，这种方式不依赖本地 Node.js 环境，使用更加便捷。

使用方法

基本转换命令

wtu -i "/path/to/miniprogram-project"

其中 "/path/to/miniprogram-project" 是要转换的小程序项目目录路径。如果路径中包含空格，请使用引号包裹。

高级选项

工具提供了多个转换选项以满足不同需求：

合并 wxss 到 vue 文件

wtu -i "./miniprogram-project" -m

转换为 vue-cli 项目结构

wtu -i "./miniprogram-project" -c

转换 template 和 include 标签为单独组件

wtu -i "./miniprogram-project" -t

转换后的项目结构

转换完成后，会在原小程序项目同级目录生成一个新的项目目录，命名规则为：

• 普通转换：原项目名_uni
• vue-cli 转换：原项目名_uni-cli

生成的项目可以直接使用 HBuilderX 导入并进行后续开发。

核心功能特性

组件转换支持

工具支持多种小程序组件的转换，包括：

• Vant 组件库的转换处理
• 原生小程序组件的适配
• 自定义组件的识别和转换

语法转换

• WXML 到 Vue 模板的转换
• WXSS 到 CSS/SCSS 的转换
• JavaScript 逻辑的适配和优化
• 生命周期函数的映射
• API 调用的兼容处理

资源处理

• 图片资源的路径转换和复制
• 样式文件的合并和优化
• 第三方库的兼容处理

项目架构

项目采用模块化设计，主要包含以下几个核心模块：

转换器模块 (src/transformers)

包含各种类型的转换器，负责处理不同的转换场景：

• 组件转换器 (component)
• 函数转换器 (function)
• 生命周期转换器 (lifecycle)
• 属性转换器 (properties)
• 特殊结构转换器 (specialStructure)

页面处理模块 (src/page)

负责处理页面级别的转换，包括：

• 脚本转换 (script)
• 样式转换 (style)
• 模板转换 (template)

工具模块 (src/utils)

提供各种工具函数，包括：

• AST 操作工具
• 路径处理工具
• 变量处理工具
• 日志工具

技术实现

项目基于 AST（抽象语法树）技术实现代码转换，主要依赖：

• Babel 用于 JavaScript 代码解析和生成
• 自定义解析器用于 WXML 和 WXSS 处理
• GoGoCode 提供基础的代码转换能力

转换示例

转换前的小程序代码：

// 小程序页面 JS
Page({
  data: {
    message: 'Hello MiniProgram'
  },
  onLoad: function() {
    console.log('页面加载')
  }
})

转换后的 uni-app 代码：

// Vue 页面
export default {
  data() {
    return {
      message: 'Hello MiniProgram'
    }
  },
  onLoad() {
    console.log('页面加载')
  }
}

注意事项

1. 版本兼容性：确保使用匹配的 Node.js 版本
2. 项目备份：转换前建议备份原项目
3. 依赖检查：转换后需要检查第三方依赖的兼容性
4. 手动调整：复杂项目可能需要进行手动调整和优化

支持的小程序平台

• 微信小程序
• QQ 小程序
• 头条/抖音小程序
• 支付宝/钉钉小程序
• 百度小程序

总结

miniprogram-to-uniapp 工具为开发者提供了从小程序生态迁移到 uni-app 多端开发框架的便捷途径。通过自动化的代码转换和处理，大大减少了手动迁移的工作量，让开发者能够更快速地实现多平台部署的目标。

对于想要尝试多端开发的开发者来说，这个工具是一个不可或缺的利器，能够帮助你快速将现有小程序项目转换为具有更广泛平台支持能力的 uni-app 项目。