npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@uni-helper/vite-plugin-uni-platform

v0.2.2

Published

Per-platform compilation for uni-app applications by file name suffix, using Vite

Readme

@uni-helper/vite-plugin-uni-platform

按文件名分流的平台编译插件:index.h5.vue 只在 H5 生效,index.mp-weixin.vue 只在小程序生效。

不想看文档?直接问 AI 🤖

请考虑持续赞助以维持该项目的持续健康发展,非常感谢!🙏

简介

uni-app 项目里想给某个平台单独写一份页面或工具函数,一般得在代码里堆 #ifdef。这个插件把分流搬到文件名上:带平台后缀的文件只在对应平台参与构建,其他平台看不到它,源码里也不用写条件判断。

插件只做文件替换,不改写文件内容,所以对 .vue、.ts、.scss 一视同仁。平台的判断依据是 UNI_CUSTOM_SCRIPT 或 UNI_PLATFORM,自定义编译脚本(比如 uni -p h5-weixin)也能用。

安装

pnpm i -D @uni-helper/vite-plugin-uni-platform

peer 依赖是 vite ^5.0.0。

[!IMPORTANT] 本插件现在只构建 ESM 产物,exports 只有 import 字段,所以 Vite 配置文件需要按 ESM 加载:命名为 vite.config.mts,或者在 package.json 里设置 "type": "module"。已发布的 0.1.x 同时提供 CJS 和 ESM 入口。

配置按 ESM 加载后,@dcloudio/vite-plugin-uni 的 CJS 默认导出拿到的是模块对象而不是函数,需要换成 @uni-helper/plugin-uni 的 ESM 导出。

快速开始

// vite.config.mts
import Uni from '@uni-helper/plugin-uni'
import UniPlatform from '@uni-helper/vite-plugin-uni-platform'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniPlatform(),
    Uni(),
  ],
})

目录里准备两份文件:

src/pages/index.vue           # 所有平台的基础版本
src/pages/index.h5.vue        # 只在 H5 生效,覆盖上面的基础版本
src/pages/index.mp-weixin.vue # 只在微信小程序生效

构建 H5 时 pages/index 用的是 index.h5.vue,构建微信小程序时用的是 index.mp-weixin.vue。

使用

扫描规则

平台名来自 @uni-helper/uni-env:存在 uni-app 自定义编译脚本时取 UNI_CUSTOM_SCRIPT,否则取 UNI_PLATFORM。

判定平台文件只看文件名:去掉扩展名后以 .{platform} 结尾就算。后缀加在文件名最后一个点之前,目录名里的点不算:

pages/index.h5.vue          # 算,H5 的页面
pages/v1.2/detail.h5.vue    # 算,H5 的页面;v1.2 是目录名
pages/v1.2/detail.vue       # 不算

插件不扫目录、不改写文件内容,只在解析时替换路径,所以 .vue、.ts、.scss 一视同仁。参与替换的范围由 include(默认 **/*)和 exclude(默认 node_modules、.git)决定。

处理规则

resolveId 依次做三件事:

  1. 导入本来就有当前平台后缀,直接交给后面的插件。
  2. 原路径能解析,交给 load 处理。load 先看当前平台的平台文件,存在就直接读它,否则用原文件。这一步就是“平台文件覆盖基础文件”。
  3. 原路径解析不到,拼上当前平台再解析一次。解析到就用平台文件;小程序端的 .vue 返回平台文件自己的路径,其余情况返回拼接后的结果。

两条路都失败时构建报错,报错带「缺少基础实现」,与 Vite 默认的 Cannot find module 区分:

缺少基础实现:无法解析 "/abs/src/platform/greeting"。基础文件不存在,当前平台 mp-weixin 的文件 "/abs/src/platform/greeting.mp-weixin" 也不存在。

能拿到导入方时(resolveId 路径),报文末尾会追加 导入方:…;requireResolve 补丁路径拿不到导入方,只有前面两句。

只给项目内的文件报这个错:resolveId 路径看相对路径和绝对路径,requireResolve 补丁路径看绝对路径。包名解析失败保留原错误。

基础文件和平台文件

两种文件同时存在时,平台文件覆盖基础文件,文件内容整个换掉。导入不用写平台后缀:

flowchart LR
    import["import pages/index"] --> exists{"有 index.PLATFORM.vue 吗"}
    exists -->|"有"| platform["用 index.PLATFORM.vue"]
    exists -->|"没有"| base["用 index.vue"]
    exists -->|"两边都没有"| error["报缺少基础实现"]
// 磁盘上只有 utils/test.h5.ts 和 utils/test.mp-weixin.ts
import { sum } from '@/utils/test'

只有平台文件、没有基础文件时可以解析,前提是当前平台有自己的文件。换到没有对应文件的平台构建,就会报上面那个错,所以建议至少留一份基础实现。

小程序里的 vue 文件

小程序端(UNI_PLATFORM 以 mp- 开头)的 .vue 文件,插件返回平台文件自己的路径,其余情况返回拼接后的解析结果。这样小程序产物按平台文件命名,比如 pages/index.mp-weixin.wxml,而不是让 uni 把平台文件当成另一个页面注册进去。

与 @uni-helper/vite-plugin-uni-pages 一起使用

@uni-helper/vite-plugin-uni-pages 0.6.1 在 configResolved 里按插件名 vite-plugin-uni-platform 认出本插件,自己过滤掉带其他平台后缀的页面并把后缀剥掉(pages/index.h5.vue 生成 /pages/index),不需要再写 onBeforeWriteFile。

import Uni from '@uni-helper/plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import UniPlatform from '@uni-helper/vite-plugin-uni-platform'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniPlatform(),
    UniPages(),
    Uni(),
  ],
})

uni-pages 只按插件名识别,所以本插件不能被改名,也不能被别的插件包一层,否则它认不出来,pages.json 里会混进其他平台的页面。两者在插件列表里的先后顺序没有要求。

用 uni-pages 的 prepare() 提前生成页面配置时,platformSuffix 必须和插件列表一致:

export default defineConfig(async () => ({
  plugins: [
    await UniPages().prepare({ platformSuffix: true }),
    UniPlatform(),
    Uni(),
  ],
}))

用 TypeScript 检查没有实体文件的导入

@/utils/test 在磁盘上没有对应文件,tsc 找不到它。给类型检查补一个声明就行,playground 里的 src/utils/test.d.ts 就是这么做的:

export declare const sum: (a: number, b: number) => string

API 参考

VitePluginUniPlatform(options?)

创建插件实例,具名导出和默认导出都有。插件名是 vite-plugin-uni-platform,enforce: 'pre'。

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | include | FilterPattern | '**/*' | 参与替换的文件,交给 Vite 的 createFilter | | exclude | FilterPattern | [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/] | 跳过的文件,同样是 createFilter 规则 |

UniPlatform({
  include: 'src/**/*',
  exclude: [/[\\/]node_modules[\\/]/, /[\\/]dist[\\/]/],
})

resolveId 先看导入本身是否已带当前平台后缀(带就直接放行),再走默认解析;默认解析失败时才把平台名插进文件名重试,解析结果要过 include / exclude。load 对不带后缀的 id 拼出 {name}.{platform}{ext},文件存在就返回它的内容。

参与贡献

欢迎提交 Pull Request,请阅读 CONTRIBUTING.md 了解开发与提交规范。

许可证

MIT