原生 Vue + UniApp 的小程序或 App 项目里如何判断用户是否为首次下载应用

一：本地存储标记法（常用）

核心思路：

用 uni.setStorageSync 存一个布尔值标志，判断是否第一次进入。

Vue2 写法

javascript 复制代码

// App.vue
export default {
  onLaunch() {
    const firstEnter = uni.getStorageSync('firstEnter')
    if (!firstEnter) {
      console.log('✨ 首次进入应用')
      uni.setStorageSync('firstEnter', true)
      // 比如跳转到引导页
      uni.reLaunch({ url: '/pages/guide/guide' })
    } else {
      console.log('🚀 已经进入过')
    }
  }
}

Vue3 写法

VUE3 复制代码

// App.vue
import { onLaunch } from '@dcloudio/uni-app'

export default {
  setup() {
    onLaunch(() => {
      const hasEntered = uni.getStorageSync('hasEntered')
      if (!hasEntered) {
        console.log('✨ 首次进入')
        uni.setStorageSync('hasEntered', true)
        uni.reLaunch({ url: '/pages/guide/guide' })
      } else {
        console.log('🚀 非首次进入')
      }
    })
  }
}

优点：

实现简单、逻辑清晰；
无需网络请求；
通用于小程序、App、H5。

缺点：

卸载或清除缓存后会重新判断为"首次进入"；
无法区分同一账号在不同设备的首次进入（仅限本设备）。

适用场景：

大部分项目的启动引导页、功能介绍页。

二：App 端文件标记（数据在设备中能保存更久，不容易被清除或覆盖。）

核心思路：

通过 plus.io（仅 App 端可用）在本地文件系统中保存标志文件，能防止被清除缓存影响。

vue2写法

vue2 复制代码

// App.vue
export default {
  onLaunch() {
    // 仅在 App 端有效
    #ifdef APP-PLUS
    console.log('App 启动，检测是否首次进入...')
    plus.io.resolveLocalFileSystemURL('_doc/', (entry) => {
      // 尝试获取 firstEnter.txt 文件（create:false 表示不自动创建）
      entry.getFile(
        'firstEnter.txt',
        { create: false },
        (fileEntry) => {
          // 文件存在 → 非首次进入
          console.log('🚀 已存在文件 -> 非首次进入')
          // 你可以在这里执行"老用户逻辑"
        },
        (error) => {
          // 文件不存在 → 首次进入
          console.log('✨ 文件不存在 -> 首次进入')
          // 创建文件以记录状态
          entry.getFile('firstEnter.txt', { create: true }, (newFile) => {
            console.log('✅ 已创建标记文件，记录首次进入')
            // 执行首次进入逻辑，比如引导页
            uni.reLaunch({ url: '/pages/guide/guide' })
          })
        }
      )
    }, (err) => {
      console.error('❌ resolveLocalFileSystemURL 解析失败:', err)
    })
    #endif
  }
}

vue3写法

vue3 复制代码

// App.vue
import { onLaunch } from '@dcloudio/uni-app'

export default {
  setup() {
    onLaunch(() => {
      // 仅在 App 端有效
      #ifdef APP-PLUS
      console.log('App 启动，检测是否首次进入...')
      plus.io.resolveLocalFileSystemURL(
        '_doc/',
        (entry) => {
          entry.getFile(
            'firstEnter.txt',
            { create: false },
            (fileEntry) => {
              console.log('🚀 已存在文件 -> 非首次进入')
              // 老用户逻辑放这里
            },
            (error) => {
              console.log('✨ 文件不存在 -> 首次进入')
              entry.getFile('firstEnter.txt', { create: true }, (newFile) => {
                console.log('✅ 已创建标记文件，记录首次进入')
                // 首次进入逻辑，例如跳转引导页
                uni.reLaunch({ url: '/pages/guide/guide' })
              })
            }
          )
        },
        (err) => {
          console.error('❌ resolveLocalFileSystemURL 解析失败:', err)
        }
      )
      #endif
    })
  }
}

注释

_doc/ 是 App 本地的持久化文件目录；
resolveLocalFileSystemURL 是解析逻辑路径的入口；
entry 是文件或目录对象，可以用来创建、读取、删除文件；
这些都是 HTML5+ (plus.io) 提供的 API，仅在 App 端（APP-PLUS） 可用

常见路径

目录	说明	可写	是否清除
`_doc/`	App 数据存储目录（推荐）		×（仅卸载清除）
`_downloads/`	下载文件保存目录		×
`_www/`	打包资源目录（App 安装包内）	×	×
`_documents/`	公开文档目录（用户可见）	×	×
`_temp/`	临时目录		√（系统可能清理）

_doc/ 是什么？

_doc/ 是 App 内部可读写的私有目录 。

可以理解为 App 的「本地数据区」。

类似于 Android 的 /data/data/包名/doc/ 或 iOS 的 Documents/ 文件夹。

在这个目录中保存的内容：

不会被 uni.clearStorage() 清除；

只有卸载 App 时才会被系统清理；

可以安全地读写文件，比如 .txt、.json、图片、日志等。

所以我们说它属于「高持久存储区」。

plus.io.resolveLocalFileSystemURL() 是什么？

这是 HTML5+ 提供的一个 路径解析函数 。

它的作用是把 _doc/、_www/、本地文件路径等「逻辑路径」解析为一个可以操作的 文件系统入口对象（entry） 。

语法：
lua 复制代码
plus.io.resolveLocalFileSystemURL(path, successCallback, errorCallback)
示例：
javascript 复制代码
plus.io.resolveLocalFileSystemURL('_doc/', (entry) => {
  console.log('成功解析到目录对象:', entry)
}, (err) => {
  console.error('解析失败:', err)
})
解析成功后，entry 就是一个目录对象或文件对象，可以用它来读、写、创建文件。

entry 是什么？

entry 是解析后的文件系统入口对象，可以是文件或目录。

常用方法如下：

方法作用

entry.getFile(filename, options, success, fail) 在目录下获取（或创建）文件

entry.remove(success, fail) 删除文件或目录

entry.moveTo() / copyTo() 移动或复制文件

方法	作用
`entry.getFile(filename, options, success, fail)`	在目录下获取（或创建）文件
`entry.remove(success, fail)`	删除文件或目录
`entry.moveTo()` / `copyTo()`	移动或复制文件

优点：

即使清除缓存，文件仍在；
适合需要长期判断首次进入的 App。
缺点：
仅适用于 App，不支持小程序；
代码稍复杂；
不适合纯前端（H5）运行。

适用场景：

需要高持久性首次检测（比如 App 引导页、注册流程控制）。

三：基于用户账号（后端标记）

核心思路：

当用户登录后，通过服务器接口判断该用户是否第一次使用该账号登录

php 复制代码

// login.vue
uni.login({
  success: async (res) => {
    const userInfo = await uni.request({
      url: 'https://api.xxx.com/checkFirstEnter',
      method: 'POST',
      data: { userId: res.userInfo.id }
    })
    if (userInfo.data.isFirstEnter) {
      console.log('✨ 该账号首次登录')
    } else {
      console.log('🚀 老用户')
    }
  }
})

优点：

跨设备一致；
适合有账号体系的应用；
可统计新用户注册、留存。

缺点：

依赖网络；
需要后端配合；
无法在未登录状态下判断。

适用场景：

需要区分新老用户的业务场景（如营销活动、统计分析）。