@viso/package-assets

一个用于管理和生成前端项目静态资源文件的工具包。

功能特性

• 🚀 自动扫描项目静态资源文件
• 📦 生成类型安全的资源引用文件
• 🔄 支持开发环境和生产环境的资源路径切换
• 🌐 集成 CDN 资源路径配置
• 🛠️ 提供命令行工具和 API 两种使用方式

安装

npm install @viso/package-assets

命令行使用

生成资源文件

# 生成静态资源引用文件
npx package-assets -g

# 或者
npx package-assets --generate

该命令会：

1. 扫描项目的 public 目录下的所有文件
2. 生成 src/__ASSETS__.ts 文件，包含所有资源的类型定义和加载函数
3. 在 src/index.ts 中自动导出资源模块

API 使用

createAssetsFile

生成静态资源文件：

import { createAssetsFile } from '@viso/package-assets'

// 使用默认的 public 目录
await createAssetsFile(process.cwd())

// 指定自定义资源目录
await createAssetsFile(process.cwd(), 'assets')

writeIndexFile

在 index.ts 中添加资源导出：

import { writeIndexFile } from '@viso/package-assets'

await writeIndexFile(process.cwd())

replaceDistFile

替换构建文件中的 CDN 路径：

import { replaceDistFile } from '@viso/package-assets'

// 使用默认配置
await replaceDistFile(process.cwd())

// 自定义配置
await replaceDistFile(
  process.cwd(),
  'dist',
  '//your-cdn.com/static'
)

生成的文件结构

运行工具后，会在 src 目录下生成 __ASSETS__.ts 文件：

import { __BASE_URL__, __CDN_BASE_PATH__ } from './__BASE_URL__'

const ASSETS_ALIAS = {
  'icon/logo.png': 'icon/logo.png',
  'images/banner.jpg': 'images/banner.jpg'
} as const

export type AssetsAlias = typeof ASSETS_ALIAS
export type AssetKey = keyof AssetsAlias

export const Assets = {
  load: (key: AssetKey, useFs: boolean = true) => {
    const asset = ASSETS_ALIAS[key]
    if (process.env.NODE_ENV === 'production') {
      return __CDN_BASE_PATH__ + '/' + asset
    } else {
      return useFs ? `@fs/${__BASE_URL__}/public/${asset}` : `${__BASE_URL__}/public/${asset}`
    }
  }
}

使用示例

在项目中使用生成的资源：

import { Assets } from './src/__ASSETS__'

// 加载图片资源
const logoUrl = Assets.load('icon/logo.png')

// 在 React 组件中使用
function App() {
  return (
    <div>
      <img src={Assets.load('icon/logo.png')} alt="Logo" />
      <img src={Assets.load('images/banner.jpg')} alt="Banner" />
    </div>
  )
}

环境配置

工具会根据 NODE_ENV 环境变量自动切换资源路径：

• 开发环境: 使用本地文件路径 (@fs/ 前缀或相对路径)
• 生产环境: 使用 CDN 路径

依赖项

• @viso/package-utils: 包工具函数
• commander: 命令行参数解析
• fast-glob: 快速文件匹配
• fs-extra: 增强的文件系统操作

许可证

本项目使用 MIT 许可证。