nuxt-gin-tools 0.2.18 → 0.2.19

package/README.md

@@ -43,6 +43,19 @@ 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`
@@ -53,6 +66,12 @@ nuxt-gin dev
 
 Go 监听规则来自 `.go-watch.json`（见下文）。
 
+可用参数：
+
+- `--skip-go`：只启动 Nuxt
+- `--skip-nuxt`：只启动 Go
+- `--no-cleanup`：跳过 develop 前的 cleanup/install 检查
+
 ### `nuxt-gin install`
 
 - 总是执行：`npx nuxt prepare`
@@ -68,6 +87,53 @@ Go 监听规则来自 `.go-watch.json`（见下文）。
 
 执行工具链内置的构建与打包逻辑。
 
+可用参数：
+
+- `--skip-go`：跳过 Go 构建
+- `--skip-nuxt`：跳过 Nuxt 静态构建
+- `--binary-name <name>`：自定义 `.build/.server` 下的 Go 二进制名称
+
+### `pack.config.ts` / `pack.config.json`
+
+`nuxt-gin build` 会自动读取项目根目录中的打包配置，优先级如下：
+
+1. `pack.config.ts`
+2. `pack.config.js`
+3. `pack.config.cjs`
+4. `pack.config.mjs`
+5. `pack.config.json`
+
+如果同时存在多个配置文件，会输出 `warn`，并按上面的优先级选择第一个。
+
+推荐使用 `pack.config.ts`：
+
+```ts
+import createPackConfig from 'nuxt-gin-tools/src/pack';
+
+export default createPackConfig({
+  zipName: 'server.7z',
+  extraFilesGlobs: ['prisma/**'],
+  packageJson: {
+    private: true,
+  },
+});
+```
+
+兼容旧的 `pack.config.json`：
+
+```json
+{
+  "zipName": "server.7z",
+  "extraFilesGlobs": ["prisma/**"]
+}
+```
+
+配置校验规则：
+
+- 明显的类型错误会直接 `error` 并终止打包
+- 可继续执行但可能有歧义的情况会输出 `warn`
+- 例如 `zipPath` 与 `zipName` 同时出现时，会提示 `zipPath` 优先生效
+
 ### `nuxt-gin cleanup`
 
 清理由工具链生成的临时目录和产物。
@@ -76,6 +142,17 @@ Go 监听规则来自 `.go-watch.json`（见下文）。
 
 执行项目约定的更新逻辑。
 
+默认策略偏保守：
+
+- Node：`pnpm update`
+- Go：`go get -u=patch ./... && go mod tidy`
+
+可用参数：
+
+- `--latest`：切换为更激进的升级策略
+- `--skip-go`：跳过 Go 依赖更新
+- `--skip-node`：跳过 Node 依赖更新
+
 ## 配置
 
 ### 1) `server.config.json`
@@ -148,3 +225,4 @@ NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
 
 - Go 侧热更新已不再依赖 Air。
 - 当前方案为：`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.19",
   "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;