nuxt-gin-tools 0.2.18 → 0.2.20

package/README.md

@@ -1,102 +1,426 @@
-# nuxt-gin-tools
+# nuxt-gin-tools 🧰
 
-`nuxt-gin-tools` 是 `nuxt-gin-starter` 的配套开发工具包，提供 Nuxt + Gin 项目的统一命令入口。
+[![npm version](https://img.shields.io/npm/v/nuxt-gin-tools?style=flat-square)](https://www.npmjs.com/package/nuxt-gin-tools)
+[![npm downloads](https://img.shields.io/npm/dm/nuxt-gin-tools?style=flat-square)](https://www.npmjs.com/package/nuxt-gin-tools)
+[![Node](https://img.shields.io/badge/Node-18%2B-339933?logo=node.js&logoColor=white&style=flat-square)](https://nodejs.org)
+[![Nuxt](https://img.shields.io/badge/Nuxt-4.x-00DC82?logo=nuxt&logoColor=white&style=flat-square)](https://nuxt.com)
+[![Go](https://img.shields.io/badge/Go-supported-00ADD8?logo=go&logoColor=white&style=flat-square)](https://go.dev)
+[![License](https://img.shields.io/badge/license-MIT-0b5fff?style=flat-square)](./LICENSE)
 
-核心目标：
-- 一条命令启动前后端开发环境
-- 自动处理 Go 侧依赖和文件监听重启
-- 提供 OpenAPI 代码生成与构建打包辅助
+`nuxt-gin-tools` is the companion CLI for [`nuxt-gin-starter`](https://github.com/RapboyGao/nuxt-gin-starter.git), built to make **Nuxt + Gin** development feel like one coherent workflow instead of two separate toolchains.
 
-## 功能概览
+Quick Jump:
 
-- `nuxt-gin dev`
-  - 启动 Nuxt 开发服务
-  - 启动 Go 文件监听（基于 `chokidar`）
-  - Go 文件变化后自动重启 `go run main.go`
-- `nuxt-gin install`
-  - 执行 Nuxt prepare
-  - 如果检测到 Go，则执行 `go mod download && go mod tidy`
-- `nuxt-gin gen`
-  - 基于 `openapi.yaml` 生成 Go / TS API 代码
-- `nuxt-gin build`
-  - 执行项目构建与打包流程
-- `nuxt-gin cleanup`
-  - 清理开发产物
-- `nuxt-gin update`
-  - 执行依赖更新流程
+- [English](#english)
+- [中文](#中文)
 
-## 安装
+## English
 
-在 `nuxt-gin-starter` 项目中作为依赖安装：
+### ✨ Highlights
+
+- 🚀 One command to run Nuxt dev + Go watcher together
+- 🔁 Automatic Go restart on file changes with `chokidar`
+- 📦 Build-and-pack workflow for deployment artifacts
+- 🧩 `pack.config.ts` support with typed config helper
+- 🛡️ Config validation with `warn` and `error` feedback
+- 🔧 Useful CLI switches for partial workflows like `--skip-go`
+
+### 📦 Install
 
 ```bash
-pnpm add nuxt-gin-tools
+pnpm add -D nuxt-gin-tools
 ```
 
-## 快速开始
+### ⚡ Quick Start
 
 ```bash
-# 初始化依赖（可选）
+# optional bootstrap
 nuxt-gin install
 
-# 启动开发
+# start Nuxt + Go together
 nuxt-gin dev
 ```
 
-## 命令说明
+Common variants:
+
+```bash
+# frontend only
+nuxt-gin dev --skip-go
+
+# go watcher only
+nuxt-gin dev --skip-nuxt
+
+# skip cleanup / bootstrap checks
+nuxt-gin dev --no-cleanup
+```
+
+### 🗂️ Commands
+
+#### `nuxt-gin dev`
+
+Runs the local development stack:
+
+- Nuxt: `npx nuxt dev --port=<nuxtPort> --host`
+- Go: watches files and restarts `go run main.go`
+
+Flags:
+
+- `--skip-go`: start Nuxt only
+- `--skip-nuxt`: start Go only
+- `--no-cleanup`: skip pre-cleanup and bootstrap checks
+
+#### `nuxt-gin install`
+
+Bootstraps the project:
+
+- always runs `npx nuxt prepare`
+- if Go is available, also runs `go mod download && go mod tidy`
+
+#### `nuxt-gin gen`
+
+Generates API code from `openapi.yaml`:
+
+- Go Gin server code
+- TypeScript axios client code
+
+#### `nuxt-gin build`
+
+Runs the build-and-pack flow.
+
+Flags:
+
+- `--skip-go`: skip Go build
+- `--skip-nuxt`: skip Nuxt static build
+- `--binary-name <name>`: override the Go binary name under `.build/.server`
+
+#### `nuxt-gin cleanup`
+
+Removes generated temp files and build output.
+
+#### `nuxt-gin update`
+
+Updates project dependencies with a conservative default strategy:
+
+- Node: `pnpm update`
+- Go: `go get -u=patch ./... && go mod tidy`
+
+Flags:
+
+- `--latest`: switch to a more aggressive upgrade strategy
+- `--skip-go`: skip Go dependency updates
+- `--skip-node`: skip Node dependency updates
+
+### 🧩 `pack.config.ts` / `pack.config.json`
+
+`nuxt-gin build` can auto-load pack config from the project root with this priority:
+
+1. `pack.config.ts`
+2. `pack.config.js`
+3. `pack.config.cjs`
+4. `pack.config.mjs`
+5. `pack.config.json`
+
+If multiple config files exist, the CLI prints a `warn` and uses the first one by priority.
+
+Recommended TypeScript form:
+
+```ts
+import createPackConfig from 'nuxt-gin-tools/src/pack';
+
+export default createPackConfig({
+  zipName: 'server.7z',
+  extraFilesGlobs: ['prisma/**'],
+  packageJson: {
+    private: true,
+  },
+});
+```
+
+Legacy JSON is still supported:
+
+```json
+{
+  "zipName": "server.7z",
+  "extraFilesGlobs": ["prisma/**"]
+}
+```
+
+Validation behavior:
+
+- ❌ obvious type problems produce an `error` and stop packing
+- ⚠️ ambiguous but survivable cases produce a `warn`
+- 📝 example: if both `zipPath` and `zipName` are present, `zipPath` wins and a warning is shown
+
+### 🧱 `pack.config.ts` Helper
+
+Use the helper from [`src/pack.ts`](./src/pack.ts):
+
+```ts
+import createPackConfig from 'nuxt-gin-tools/src/pack';
+
+export default createPackConfig({
+  serverPath: '.build/production/server',
+  zipName: 'release.7z',
+});
+```
+
+It provides:
+
+- `PackConfig` type
+- `createPackConfig(config)` helper
+- default export as `createPackConfig`
+
+### ⚙️ Runtime Config
+
+#### `server.config.json`
+
+`dev` reads this file for the main runtime wiring:
+
+- `ginPort`: Gin server port
+- `nuxtPort`: Nuxt dev port
+- `baseUrl`: Nuxt base URL
+- `killPortBeforeDevelop`: whether to free ports before dev, default `true`
+- `cleanupBeforeDevelop`: whether to cleanup before dev, default `false`
+
+#### Frontend Runtime Exposure
+
+`createDefaultConfig` injects values into Nuxt `runtimeConfig.public`:
+
+- `public.ginPort`: available in development, `null` in production
+- `public.isDevelopment`: direct development flag
+
+Example:
+
+```ts
+const config = useRuntimeConfig();
+const ginPort = config.public.ginPort;
+const isDevelopment = config.public.isDevelopment;
+```
+
+#### `.go-watch.json`
 
-### `nuxt-gin dev`
+Go watcher rules come from `.go-watch.json`:
+
+```json
+{
+  "tmpDir": ".build/.server",
+  "testDataDir": "testdata",
+  "includeExt": ["go", "tpl", "html"],
+  "includeDir": [],
+  "includeFile": [],
+  "excludeDir": [
+    "assets",
+    ".build/.server",
+    "vendor",
+    "testdata",
+    "node_modules",
+    "vue",
+    "api",
+    ".vscode",
+    ".git"
+  ],
+  "excludeFile": [],
+  "excludeRegex": ["_test.go"]
+}
+```
+
+You can also point to a custom watcher config:
+
+```bash
+NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
+```
+
+### 🖥️ Environment
+
+- Node.js
+- pnpm
+- Go, if you need the Gin side to run
+- `openapi-generator-cli`, only for `nuxt-gin gen`
+
+### 📝 Notes
+
+- 💨 Go hot reload no longer depends on Air
+- 👀 The current watcher model is `chokidar` + restart `go run main.go`
+- 🪟 Packaging uses platform-aware executable naming: Windows defaults to `.exe`, Linux/macOS defaults to no extension
+
+---
+
+## 中文
+
+### ✨ 功能亮点
+
+- 🚀 一条命令同时启动 Nuxt 与 Go 开发环境
+- 🔁 基于 `chokidar` 的 Go 文件监听与自动重启
+- 📦 内置构建与打包流程，适合产物发布
+- 🧩 支持 `pack.config.ts`，并提供类型化 helper
+- 🛡️ 对打包配置做校验，区分 `warn` 和 `error`
+- 🔧 支持 `--skip-go` 等局部开发参数
+
+### 📦 安装
+
+```bash
+pnpm add -D nuxt-gin-tools
+```
+
+### ⚡ 快速开始
+
+```bash
+# 可选：初始化依赖
+nuxt-gin install
+
+# 同时启动前后端开发环境
+nuxt-gin dev
+```
+
+常见变体：
+
+```bash
+# 仅启动前端
+nuxt-gin dev --skip-go
+
+# 仅启动 Go 监听
+nuxt-gin dev --skip-nuxt
+
+# 跳过预清理 / 预安装检查
+nuxt-gin dev --no-cleanup
+```
+
+### 🗂️ 命令说明
+
+#### `nuxt-gin dev`
+
+启动本地开发环境：
 
-开发模式下会并行运行：
 - Nuxt：`npx nuxt dev --port=<nuxtPort> --host`
-- Go：监听变更并运行 `go run main.go`
+- Go：监听文件变化并重启 `go run main.go`
+
+参数：
+
+- `--skip-go`：只启动 Nuxt
+- `--skip-nuxt`：只启动 Go
+- `--no-cleanup`：跳过 develop 前的 cleanup / bootstrap 检查
+
+#### `nuxt-gin install`
+
+用于初始化项目：
+
+- 总是执行 `npx nuxt prepare`
+- 检测到 Go 后，额外执行 `go mod download && go mod tidy`
+
+#### `nuxt-gin gen`
+
+基于 `openapi.yaml` 生成 API 代码：
+
+- Go Gin server 代码
+- TypeScript axios 客户端代码
+
+#### `nuxt-gin build`
+
+执行构建与打包流程。
+
+参数：
+
+- `--skip-go`：跳过 Go 构建
+- `--skip-nuxt`：跳过 Nuxt 静态构建
+- `--binary-name <name>`：覆盖 `.build/.server` 下的 Go 二进制名称
+
+#### `nuxt-gin cleanup`
 
-Go 监听规则来自 `.go-watch.json`（见下文）。
+清理临时文件与构建产物。
 
-### `nuxt-gin install`
+#### `nuxt-gin update`
 
-- 总是执行：`npx nuxt prepare`
-- 检测到 Go 时额外执行：`go mod download && go mod tidy`
+按偏保守的默认策略更新依赖：
 
-### `nuxt-gin gen`
+- Node：`pnpm update`
+- Go：`go get -u=patch ./... && go mod tidy`
 
-依赖 `openapi-generator-cli`，默认会：
-- 生成 Go Gin server 相关代码
-- 生成 TypeScript axios 客户端代码
+参数：
 
-### `nuxt-gin build`
+- `--latest`：切换成更激进的升级策略
+- `--skip-go`：跳过 Go 依赖更新
+- `--skip-node`：跳过 Node 依赖更新
 
-执行工具链内置的构建与打包逻辑。
+### 🧩 `pack.config.ts` / `pack.config.json`
 
-### `nuxt-gin cleanup`
+`nuxt-gin build` 会自动读取项目根目录中的打包配置，优先级如下：
 
-清理由工具链生成的临时目录和产物。
+1. `pack.config.ts`
+2. `pack.config.js`
+3. `pack.config.cjs`
+4. `pack.config.mjs`
+5. `pack.config.json`
+
+如果同时存在多个配置文件，CLI 会输出 `warn`，并按优先级选择第一个。
+
+推荐使用 TypeScript 写法：
+
+```ts
+import createPackConfig from 'nuxt-gin-tools/src/pack';
+
+export default createPackConfig({
+  zipName: 'server.7z',
+  extraFilesGlobs: ['prisma/**'],
+  packageJson: {
+    private: true,
+  },
+});
+```
+
+旧的 JSON 配置仍然兼容：
+
+```json
+{
+  "zipName": "server.7z",
+  "extraFilesGlobs": ["prisma/**"]
+}
+```
+
+校验规则：
+
+- ❌ 明显类型错误会直接 `error` 并终止打包
+- ⚠️ 可继续执行但存在歧义的情况会输出 `warn`
+- 📝 例如同时设置 `zipPath` 和 `zipName` 时，会提示 `zipPath` 优先生效
+
+### 🧱 `pack.config.ts` Helper
+
+可通过 [`src/pack.ts`](./src/pack.ts) 使用 helper：
+
+```ts
+import createPackConfig from 'nuxt-gin-tools/src/pack';
+
+export default createPackConfig({
+  serverPath: '.build/production/server',
+  zipName: 'release.7z',
+});
+```
 
-### `nuxt-gin update`
+它提供：
 
-执行项目约定的更新逻辑。
+- `PackConfig` 类型
+- `createPackConfig(config)` 函数
+- 默认导出即 `createPackConfig`
 
-## 配置
+### ⚙️ 运行时配置
 
-### 1) `server.config.json`
+#### `server.config.json`
 
-`dev` 命令会读取该文件，常用字段：
+`dev` 命令会读取这个文件来确定运行方式：
 
-- `ginPort`: Gin 服务端口
-- `nuxtPort`: Nuxt 开发端口
-- `baseUrl`: Nuxt baseUrl
-- `killPortBeforeDevelop`: 开发前是否释放端口（默认 `true`）
-- `cleanupBeforeDevelop`: 开发前是否执行 cleanup（默认 `false`）
+- `ginPort`：Gin 服务端口
+- `nuxtPort`：Nuxt 开发端口
+- `baseUrl`：Nuxt 的 base URL
+- `killPortBeforeDevelop`：开发前是否释放端口，默认 `true`
+- `cleanupBeforeDevelop`：开发前是否执行 cleanup，默认 `false`
 
-### 3) 开发环境向前端暴露 `ginPort`
+#### 前端运行时暴露
 
-`createDefaultConfig` 会在 Nuxt `runtimeConfig.public` 中注入 `ginPort`：
+`createDefaultConfig` 会把以下值注入 Nuxt `runtimeConfig.public`：
 
-- 开发环境：`useRuntimeConfig().public.ginPort` 为 `server.config.json` 的 `ginPort`
-- 生产环境：`useRuntimeConfig().public.ginPort` 为 `null`
-- 所有环境：`useRuntimeConfig().public.isDevelopment` 直接暴露当前是否开发环境
+- `public.ginPort`：开发环境可读，生产环境为 `null`
+- `public.isDevelopment`：当前是否为开发环境
 
-前端示例：
+示例：
 
 ```ts
 const config = useRuntimeConfig();
@@ -104,9 +428,9 @@ const ginPort = config.public.ginPort;
 const isDevelopment = config.public.isDevelopment;
 ```
 
-### 2) `.go-watch.json`
+#### `.go-watch.json`
 
-Go 监听配置文件，示例：
+Go 监听规则来自 `.go-watch.json`：
 
 ```json
 {
@@ -131,20 +455,21 @@ Go 监听配置文件，示例：
 }
 ```
 
-也支持环境变量指定路径：
+也支持通过环境变量指定：
 
 ```bash
 NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
 ```
 
-## 环境依赖
+### 🖥️ 环境依赖
 
 - Node.js
 - pnpm
-- Go（需要运行 Gin 侧开发与依赖下载时）
-- `openapi-generator-cli`（仅 `nuxt-gin gen` 需要）
+- Go，若需要运行 Gin 侧开发流程
+- `openapi-generator-cli`，仅 `nuxt-gin gen` 需要
 
-## 说明
+### 📝 说明
 
-- Go 侧热更新已不再依赖 Air。
-- 当前方案为：`chokidar` 监听文件变化 + 重启 `go run main.go`。
+- 💨 Go 热更新不再依赖 Air
+- 👀 当前 Go 开发监听方案为 `chokidar` + 重启 `go run main.go`
+- 🪟 打包时会按平台生成可执行文件名：Windows 默认 `.exe`，Linux/macOS 默认无扩展名

package/commands/pack.d.ts

@@ -1,56 +1,4 @@
-import type { BuildOptions } from "./builder";
-export interface PackConfig extends BuildOptions {
-    /**
-     * 额外需要打包的文件映射
-     * key: 源文件路径（相对于项目根目录或绝对路径）
-     * value: 打包后对应位置（相对于服务器构建目录或绝对路径）
-     */
-    extraFiles?: Record<string, string>;
-    /**
-     * 额外需要打包的文件 Glob（相对于项目根目录）
-     */
-    extraFilesGlobs?: string[];
-    /**
-     * 排除文件/目录 Glob（相对于项目根目录）
-     */
-    exclude?: string[];
-    /**
-     * 打包输出 zip 名称（相对于默认 zip 目录）
-     */
-    zipName?: string;
-    /**
-     * 打包输出 zip 路径（相对于项目根目录或绝对路径）
-     */
-    zipPath?: string;
-    /**
-     * 服务器构建输出目录（相对于项目根目录或绝对路径）
-     */
-    serverPath?: string;
-    /**
-     * 打包前钩子
-     */
-    beforePack?: () => Promise<void> | void;
-    /**
-     * 打包后钩子
-     */
-    afterPack?: (zipPath: string) => Promise<void> | void;
-    /**
-     * 是否清理 dist
-     */
-    cleanDist?: boolean;
-    /**
-     * 是否写入启动脚本和 package.json
-     */
-    writeScripts?: boolean;
-    /**
-     * 写入/覆盖 package.json 内容
-     */
-    packageJson?: Record<string, unknown>;
-    /**
-     * 复制时是否覆盖同名文件
-     */
-    overwrite?: boolean;
-}
+import type { PackConfig } from "../src/pack";
 /**
  * 生成相对于服务器构建目录的绝对路径
  * @param relativePath - 相对路径
@@ -61,6 +9,10 @@ export declare const ZIP_PATH: string;
 export declare const SERVER_PATH: string;
 export declare const ORIGINAL_DIST_PATH: string;
 export declare const PACK_CONFIG_PATH: string;
+export declare const PACK_CONFIG_TS_PATH: string;
+export declare const PACK_CONFIG_JS_PATH: string;
+export declare const PACK_CONFIG_CJS_PATH: string;
+export declare const PACK_CONFIG_MJS_PATH: string;
 export declare const BUILD_EXECUTABLE: string;
 export declare const SERVER_EXECUTABLE: string;
 export declare const PACKAGE_JSON_CONTENT: {

package/commands/pack.js

@@ -45,7 +45,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FILES_TO_COPY = exports.PACKAGE_JSON_CONTENT = exports.SERVER_EXECUTABLE = exports.BUILD_EXECUTABLE = exports.PACK_CONFIG_PATH = exports.ORIGINAL_DIST_PATH = exports.SERVER_PATH = exports.ZIP_PATH = void 0;
+exports.FILES_TO_COPY = exports.PACKAGE_JSON_CONTENT = exports.SERVER_EXECUTABLE = exports.BUILD_EXECUTABLE = exports.PACK_CONFIG_MJS_PATH = exports.PACK_CONFIG_CJS_PATH = exports.PACK_CONFIG_JS_PATH = exports.PACK_CONFIG_TS_PATH = exports.PACK_CONFIG_PATH = exports.ORIGINAL_DIST_PATH = exports.SERVER_PATH = exports.ZIP_PATH = void 0;
 exports.builtPath = builtPath;
 exports.buildAndPack = buildAndPack;
 // 导入项目构建工具，用于执行 Nuxt 项目的构建流程
@@ -58,6 +58,7 @@ const FS = __importStar(require("fs-extra"));
 const Path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fast_glob_1 = __importDefault(require("fast-glob"));
+const { createJiti } = require("jiti");
 /**
  * 生成相对于服务器构建目录的绝对路径
  * @param relativePath - 相对路径
@@ -73,6 +74,10 @@ exports.SERVER_PATH = Path.resolve(process.cwd(), ".build/production/server");
 // 定义原始 dist 目录路径，用于清理操作
 exports.ORIGINAL_DIST_PATH = Path.resolve(process.cwd(), "dist");
 exports.PACK_CONFIG_PATH = Path.resolve(process.cwd(), "pack.config.json");
+exports.PACK_CONFIG_TS_PATH = Path.resolve(process.cwd(), "pack.config.ts");
+exports.PACK_CONFIG_JS_PATH = Path.resolve(process.cwd(), "pack.config.js");
+exports.PACK_CONFIG_CJS_PATH = Path.resolve(process.cwd(), "pack.config.cjs");
+exports.PACK_CONFIG_MJS_PATH = Path.resolve(process.cwd(), "pack.config.mjs");
 exports.BUILD_EXECUTABLE = os.platform() === "win32" ? "production.exe" : "production";
 exports.SERVER_EXECUTABLE = os.platform() === "win32" ? "server-production.exe" : "server-production"; // 根据操作系统选择可执行文件名
 // 定义打包后项目的 package.json 内容
@@ -90,6 +95,94 @@ const DEFAULT_FILES_TO_COPY = {
 };
 // 兼容旧导出：默认构建目录下的绝对目标路径
 exports.FILES_TO_COPY = Object.fromEntries(Object.entries(DEFAULT_FILES_TO_COPY).map(([src, dest]) => [src, builtPath(dest)]));
+function warnPackConfig(message) {
+    console.warn(`[nuxt-gin-tools][pack] WARN: ${message}`);
+}
+function errorPackConfig(message) {
+    throw new Error(`[nuxt-gin-tools][pack] ${message}`);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateStringArray(fieldName, value, issues) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        issues.push({ level: "error", message: `${fieldName} must be an array of strings` });
+        return;
+    }
+    for (const item of value) {
+        if (typeof item !== "string") {
+            issues.push({ level: "error", message: `${fieldName} must contain only strings` });
+            return;
+        }
+    }
+}
+function validateStringRecord(fieldName, value, issues) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isPlainObject(value)) {
+        issues.push({ level: "error", message: `${fieldName} must be an object of string to string` });
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof key !== "string" || typeof item !== "string") {
+            issues.push({ level: "error", message: `${fieldName} must be an object of string to string` });
+            return;
+        }
+    }
+}
+function validatePackConfig(config, sourcePath) {
+    if (!isPlainObject(config)) {
+        errorPackConfig(`${Path.basename(sourcePath)} must export an object`);
+    }
+    const issues = [];
+    const typedConfig = config;
+    const stringFields = ["binaryName", "zipName", "zipPath", "serverPath"];
+    for (const field of stringFields) {
+        const value = typedConfig[field];
+        if (value !== undefined && typeof value !== "string") {
+            issues.push({ level: "error", message: `${field} must be a string` });
+        }
+    }
+    const booleanFields = ["skipGo", "skipNuxt", "cleanDist", "writeScripts", "overwrite"];
+    for (const field of booleanFields) {
+        const value = typedConfig[field];
+        if (value !== undefined && typeof value !== "boolean") {
+            issues.push({ level: "error", message: `${field} must be a boolean` });
+        }
+    }
+    validateStringArray("extraFilesGlobs", typedConfig.extraFilesGlobs, issues);
+    validateStringArray("exclude", typedConfig.exclude, issues);
+    validateStringRecord("extraFiles", typedConfig.extraFiles, issues);
+    if (typedConfig.packageJson !== undefined && !isPlainObject(typedConfig.packageJson)) {
+        issues.push({ level: "error", message: `packageJson must be an object` });
+    }
+    if (typedConfig.beforePack !== undefined && typeof typedConfig.beforePack !== "function") {
+        issues.push({ level: "error", message: `beforePack must be a function` });
+    }
+    if (typedConfig.afterPack !== undefined && typeof typedConfig.afterPack !== "function") {
+        issues.push({ level: "error", message: `afterPack must be a function` });
+    }
+    if (typedConfig.zipName !== undefined && typedConfig.zipPath !== undefined) {
+        issues.push({ level: "warn", message: `zipPath and zipName are both set; zipPath takes precedence` });
+    }
+    if (typedConfig.skipGo === true && typedConfig.skipNuxt === true) {
+        issues.push({ level: "warn", message: `skipGo and skipNuxt are both true; build step will be skipped` });
+    }
+    for (const issue of issues) {
+        if (issue.level === "warn") {
+            warnPackConfig(`${Path.basename(sourcePath)}: ${issue.message}`);
+        }
+    }
+    const errors = issues.filter((issue) => issue.level === "error");
+    if (errors.length > 0) {
+        errorPackConfig(`${Path.basename(sourcePath)} is invalid:\n- ${errors.map((item) => item.message).join("\n- ")}`);
+    }
+    return config;
+}
 /**
  * 写入启动脚本和 package.json 文件到构建目录
  */
@@ -148,10 +241,32 @@ function mergePackageJson(base, override) {
     return Object.assign(Object.assign(Object.assign({}, base), override), { scripts: Object.assign(Object.assign({}, baseScripts), overrideScripts) });
 }
 function readPackConfigFromCwd() {
-    if (!FS.existsSync(exports.PACK_CONFIG_PATH)) {
+    const candidates = [
+        exports.PACK_CONFIG_TS_PATH,
+        exports.PACK_CONFIG_JS_PATH,
+        exports.PACK_CONFIG_CJS_PATH,
+        exports.PACK_CONFIG_MJS_PATH,
+        exports.PACK_CONFIG_PATH,
+    ].filter((configPath) => FS.existsSync(configPath));
+    if (candidates.length === 0) {
         return undefined;
     }
-    return FS.readJSONSync(exports.PACK_CONFIG_PATH);
+    if (candidates.length > 1) {
+        warnPackConfig(`multiple pack config files found (${candidates.map((item) => Path.basename(item)).join(", ")}); using ${Path.basename(candidates[0])}`);
+    }
+    const selectedPath = candidates[0];
+    let loadedConfig;
+    if (selectedPath.endsWith(".json")) {
+        loadedConfig = FS.readJSONSync(selectedPath);
+    }
+    else {
+        const jiti = createJiti(__filename, { moduleCache: false, interopDefault: true });
+        loadedConfig = jiti(selectedPath);
+    }
+    const normalizedConfig = isPlainObject(loadedConfig) && "default" in loadedConfig
+        ? loadedConfig.default
+        : loadedConfig;
+    return validatePackConfig(normalizedConfig, selectedPath);
 }
 function resolveServerPath(config) {
     if (!(config === null || config === void 0 ? void 0 : config.serverPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-gin-tools",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "This project is used as a dependency for [nuxt-gin-starter](https://github.com/RapboyGao/nuxt-gin-starter.git)",
   "bin": {
     "nuxt-gin": "index.js"
@@ -18,7 +18,8 @@
     "chokidar": "^3.6.0",
     "concurrently": "^9.2.0",
     "fast-glob": "^3.3.3",
-    "fs-extra": "^11.3.0"
+    "fs-extra": "^11.3.0",
+    "jiti": "^2.6.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/src/pack.d.ts

@@ -0,0 +1,55 @@
+import type { BuildOptions } from "../commands/builder";
+export interface PackConfig extends BuildOptions {
+    /**
+     * 额外需要打包的文件映射
+     * key: 源文件路径（相对于项目根目录或绝对路径）
+     * value: 打包后对应位置（相对于服务器构建目录或绝对路径）
+     */
+    extraFiles?: Record<string, string>;
+    /**
+     * 额外需要打包的文件 Glob（相对于项目根目录）
+     */
+    extraFilesGlobs?: string[];
+    /**
+     * 排除文件/目录 Glob（相对于项目根目录）
+     */
+    exclude?: string[];
+    /**
+     * 打包输出 zip 名称（相对于默认 zip 目录）
+     */
+    zipName?: string;
+    /**
+     * 打包输出 zip 路径（相对于项目根目录或绝对路径）
+     */
+    zipPath?: string;
+    /**
+     * 服务器构建输出目录（相对于项目根目录或绝对路径）
+     */
+    serverPath?: string;
+    /**
+     * 打包前钩子
+     */
+    beforePack?: () => Promise<void> | void;
+    /**
+     * 打包后钩子
+     */
+    afterPack?: (zipPath: string) => Promise<void> | void;
+    /**
+     * 是否清理 dist
+     */
+    cleanDist?: boolean;
+    /**
+     * 是否写入启动脚本和 package.json
+     */
+    writeScripts?: boolean;
+    /**
+     * 写入/覆盖 package.json 内容
+     */
+    packageJson?: Record<string, unknown>;
+    /**
+     * 复制时是否覆盖同名文件
+     */
+    overwrite?: boolean;
+}
+export declare function createPackConfig(config: PackConfig): PackConfig;
+export default createPackConfig;

package/src/pack.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPackConfig = createPackConfig;
+function createPackConfig(config) {
+    return config;
+}
+exports.default = createPackConfig;