nuxt-gin-tools 0.2.17 → 0.2.19

package/.go-watch.json

@@ -1,20 +1,20 @@
-{
-  "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"]
-}
+{
+  "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"]
+}

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 AlbertGao
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 AlbertGao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,150 +1,228 @@
-# nuxt-gin-tools
-
-`nuxt-gin-tools` 是 `nuxt-gin-starter` 的配套开发工具包，提供 Nuxt + Gin 项目的统一命令入口。
-
-核心目标：
-- 一条命令启动前后端开发环境
-- 自动处理 Go 侧依赖和文件监听重启
-- 提供 OpenAPI 代码生成与构建打包辅助
-
-## 功能概览
-
-- `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`
-  - 执行依赖更新流程
-
-## 安装
-
-在 `nuxt-gin-starter` 项目中作为依赖安装：
-
-```bash
-pnpm add nuxt-gin-tools
-```
-
-## 快速开始
-
-```bash
-# 初始化依赖（可选）
-nuxt-gin install
-
-# 启动开发
-nuxt-gin dev
-```
-
-## 命令说明
-
-### `nuxt-gin dev`
-
-开发模式下会并行运行：
-- Nuxt：`npx nuxt dev --port=<nuxtPort> --host`
-- Go：监听变更并运行 `go run main.go`
-
-Go 监听规则来自 `.go-watch.json`（见下文）。
-
-### `nuxt-gin install`
-
-- 总是执行：`npx nuxt prepare`
-- 检测到 Go 时额外执行：`go mod download && go mod tidy`
-
-### `nuxt-gin gen`
-
-依赖 `openapi-generator-cli`，默认会：
-- 生成 Go Gin server 相关代码
-- 生成 TypeScript axios 客户端代码
-
-### `nuxt-gin build`
-
-执行工具链内置的构建与打包逻辑。
-
-### `nuxt-gin cleanup`
-
-清理由工具链生成的临时目录和产物。
-
-### `nuxt-gin update`
-
-执行项目约定的更新逻辑。
-
-## 配置
-
-### 1) `server.config.json`
-
-`dev` 命令会读取该文件，常用字段：
-
-- `ginPort`: Gin 服务端口
-- `nuxtPort`: Nuxt 开发端口
-- `baseUrl`: Nuxt baseUrl
-- `killPortBeforeDevelop`: 开发前是否释放端口（默认 `true`）
-- `cleanupBeforeDevelop`: 开发前是否执行 cleanup（默认 `false`）
-
-### 3) 开发环境向前端暴露 `ginPort`
-
-`createDefaultConfig` 会在 Nuxt `runtimeConfig.public` 中注入 `ginPort`：
-
-- 开发环境：`useRuntimeConfig().public.ginPort` 为 `server.config.json` 的 `ginPort`
-- 生产环境：`useRuntimeConfig().public.ginPort` 为 `null`
-- 所有环境：`useRuntimeConfig().public.isDevelopment` 直接暴露当前是否开发环境
-
-前端示例：
-
-```ts
-const config = useRuntimeConfig();
-const ginPort = config.public.ginPort;
-const isDevelopment = config.public.isDevelopment;
-```
-
-### 2) `.go-watch.json`
-
-Go 监听配置文件，示例：
-
-```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"]
-}
-```
-
-也支持环境变量指定路径：
-
-```bash
-NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
-```
-
-## 环境依赖
-
-- Node.js
-- pnpm
-- Go（需要运行 Gin 侧开发与依赖下载时）
-- `openapi-generator-cli`（仅 `nuxt-gin gen` 需要）
-
-## 说明
-
-- Go 侧热更新已不再依赖 Air。
-- 当前方案为：`chokidar` 监听文件变化 + 重启 `go run main.go`。
+# nuxt-gin-tools
+
+`nuxt-gin-tools` 是 `nuxt-gin-starter` 的配套开发工具包，提供 Nuxt + Gin 项目的统一命令入口。
+
+核心目标：
+- 一条命令启动前后端开发环境
+- 自动处理 Go 侧依赖和文件监听重启
+- 提供 OpenAPI 代码生成与构建打包辅助
+
+## 功能概览
+
+- `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`
+  - 执行依赖更新流程
+
+## 安装
+
+在 `nuxt-gin-starter` 项目中作为依赖安装：
+
+```bash
+pnpm add 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-watch.json`（见下文）。
+
+可用参数：
+
+- `--skip-go`：只启动 Nuxt
+- `--skip-nuxt`：只启动 Go
+- `--no-cleanup`：跳过 develop 前的 cleanup/install 检查
+
+### `nuxt-gin install`
+
+- 总是执行：`npx nuxt prepare`
+- 检测到 Go 时额外执行：`go mod download && go mod tidy`
+
+### `nuxt-gin gen`
+
+依赖 `openapi-generator-cli`，默认会：
+- 生成 Go Gin server 相关代码
+- 生成 TypeScript axios 客户端代码
+
+### `nuxt-gin build`
+
+执行工具链内置的构建与打包逻辑。
+
+可用参数：
+
+- `--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`
+
+清理由工具链生成的临时目录和产物。
+
+### `nuxt-gin update`
+
+执行项目约定的更新逻辑。
+
+默认策略偏保守：
+
+- Node：`pnpm update`
+- Go：`go get -u=patch ./... && go mod tidy`
+
+可用参数：
+
+- `--latest`：切换为更激进的升级策略
+- `--skip-go`：跳过 Go 依赖更新
+- `--skip-node`：跳过 Node 依赖更新
+
+## 配置
+
+### 1) `server.config.json`
+
+`dev` 命令会读取该文件，常用字段：
+
+- `ginPort`: Gin 服务端口
+- `nuxtPort`: Nuxt 开发端口
+- `baseUrl`: Nuxt baseUrl
+- `killPortBeforeDevelop`: 开发前是否释放端口（默认 `true`）
+- `cleanupBeforeDevelop`: 开发前是否执行 cleanup（默认 `false`）
+
+### 3) 开发环境向前端暴露 `ginPort`
+
+`createDefaultConfig` 会在 Nuxt `runtimeConfig.public` 中注入 `ginPort`：
+
+- 开发环境：`useRuntimeConfig().public.ginPort` 为 `server.config.json` 的 `ginPort`
+- 生产环境：`useRuntimeConfig().public.ginPort` 为 `null`
+- 所有环境：`useRuntimeConfig().public.isDevelopment` 直接暴露当前是否开发环境
+
+前端示例：
+
+```ts
+const config = useRuntimeConfig();
+const ginPort = config.public.ginPort;
+const isDevelopment = config.public.isDevelopment;
+```
+
+### 2) `.go-watch.json`
+
+Go 监听配置文件，示例：
+
+```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"]
+}
+```
+
+也支持环境变量指定路径：
+
+```bash
+NUXT_GIN_WATCH_CONFIG=/path/to/.go-watch.json
+```
+
+## 环境依赖
+
+- Node.js
+- pnpm
+- Go（需要运行 Gin 侧开发与依赖下载时）
+- `openapi-generator-cli`（仅 `nuxt-gin gen` 需要）
+
+## 说明
+
+- Go 侧热更新已不再依赖 Air。
+- 当前方案为：`chokidar` 监听文件变化 + 重启 `go run main.go`。
+- 打包时会按当前平台生成可执行文件名：Windows 默认 `.exe`，Linux/macOS 默认无扩展名。

package/commands/builder.d.ts

@@ -1,2 +1,7 @@
-export declare function build(): Promise<import("concurrently").CloseEvent[]>;
+export type BuildOptions = {
+    binaryName?: string;
+    skipGo?: boolean;
+    skipNuxt?: boolean;
+};
+export declare function build(options?: BuildOptions): Promise<void> | Promise<import("concurrently").CloseEvent[]>;
 export default build;

package/commands/builder.js

@@ -7,20 +7,29 @@ exports.build = build;
 const concurrently_1 = __importDefault(require("concurrently"));
 const fs_extra_1 = require("fs-extra");
 const path_1 = require("path");
+const os_1 = __importDefault(require("os"));
 const cwd = process.cwd();
-function build() {
+const defaultBinaryName = os_1.default.platform() === "win32" ? "production.exe" : "production";
+function build(options = {}) {
     (0, fs_extra_1.ensureDirSync)((0, path_1.join)(cwd, "vue/.output"));
-    return (0, concurrently_1.default)([
-        {
-            command: "go build -o ./.build/.server/production.exe .",
+    const commands = [];
+    if (!options.skipGo) {
+        commands.push({
+            command: `go build -o ./.build/.server/${options.binaryName || defaultBinaryName} .`,
             name: "go",
             prefixColor: "green",
-        },
-        {
+        });
+    }
+    if (!options.skipNuxt) {
+        commands.push({
             command: "npx nuxt generate",
             name: "nuxt",
             prefixColor: "blue",
-        },
-    ]).result;
+        });
+    }
+    if (commands.length === 0) {
+        return Promise.resolve();
+    }
+    return (0, concurrently_1.default)(commands).result;
 }
 exports.default = build;

package/commands/develop.d.ts

@@ -1,3 +1,8 @@
+export type DevelopOptions = {
+    noCleanup?: boolean;
+    skipGo?: boolean;
+    skipNuxt?: boolean;
+};
 /**
  * 启动本地开发环境。
  *
@@ -5,17 +10,17 @@
  *
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
-export declare function develop(): Promise<void>;
+export declare function develop(options?: DevelopOptions): Promise<void>;
 /**
  * 仅启动 Nuxt 开发服务（带 nuxt 标签输出）。
  *
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
-export declare function developNuxt(): Promise<void>;
+export declare function developNuxt(options?: DevelopOptions): Promise<void>;
 /**
  * 仅启动 Go 开发监听流程。
  *
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
-export declare function developGo(): Promise<void>;
+export declare function developGo(options?: DevelopOptions): Promise<void>;
 export default develop;

package/commands/develop.js

@@ -25,8 +25,12 @@ const utils_1 = require("../src/utils");
 const cwd = process.cwd();
 const serverConfig = (0, fs_extra_1.readJSONSync)((0, path_1.join)(cwd, "server.config.json"));
 function prepareDevelop() {
-    return __awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
         const cleanupBeforeDevelop = serverConfig.cleanupBeforeDevelop === true;
+        const shouldPrepare = !options.noCleanup;
+        if (!shouldPrepare) {
+            return;
+        }
         if (cleanupBeforeDevelop) {
             yield (0, cleanup_1.default)();
             yield (0, postinstall_1.default)();
@@ -63,14 +67,24 @@ function runGoDev() {
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
 function develop() {
-    return __awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
         const killPortBeforeDevelop = serverConfig.killPortBeforeDevelop !== false;
-        yield prepareDevelop();
+        yield prepareDevelop(options);
         // 在开发前确保占用端口被释放
         if (killPortBeforeDevelop) {
-            (0, utils_1.killPorts)([serverConfig.ginPort, serverConfig.nuxtPort]);
+            (0, utils_1.killPorts)([
+                options.skipGo ? undefined : serverConfig.ginPort,
+                options.skipNuxt ? undefined : serverConfig.nuxtPort,
+            ]);
         }
-        yield Promise.all([runGoDev(), runNuxtDev()]);
+        const tasks = [];
+        if (!options.skipGo) {
+            tasks.push(runGoDev());
+        }
+        if (!options.skipNuxt) {
+            tasks.push(runNuxtDev());
+        }
+        yield Promise.all(tasks);
     });
 }
 /**
@@ -79,9 +93,9 @@ function develop() {
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
 function developNuxt() {
-    return __awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
         const killPortBeforeDevelop = serverConfig.killPortBeforeDevelop !== false;
-        yield prepareDevelop();
+        yield prepareDevelop(options);
         if (killPortBeforeDevelop) {
             (0, utils_1.killPorts)([serverConfig.nuxtPort]);
         }
@@ -94,9 +108,9 @@ function developNuxt() {
  * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
  */
 function developGo() {
-    return __awaiter(this, void 0, void 0, function* () {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
         const killPortBeforeDevelop = serverConfig.killPortBeforeDevelop !== false;
-        yield prepareDevelop();
+        yield prepareDevelop(options);
         if (killPortBeforeDevelop) {
             (0, utils_1.killPorts)([serverConfig.ginPort]);
         }

package/commands/pack.d.ts

@@ -1,55 +1,4 @@
-export interface PackConfig {
-    /**
-     * 额外需要打包的文件映射
-     * 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 - 相对路径
@@ -60,6 +9,11 @@ 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: {
     private: boolean;