chore: sync

code/g3soft-libs/docs/content/index.md

@@ -1,7 +1,7 @@
 ---
 seo:
-  title: G3Soft 前端技术文档
-  description: G3Soft 自研 Vue 3 组件库、设计变量与前端工程规范。
+  title: G3Soft 技术文档
+  description: G3Soft 技术文档：组件库、设计变量、工程规范与设计决策。
 ---
 
 :::u-page-hero
@@ -9,7 +9,7 @@ seo:
 自研组件，一套规范
 
 #description
-G3Soft 前端技术文档站：组件库 API、设计变量、工程规范与设计决策，全部集中在这里。
+G3Soft 技术文档站：组件库 API、设计变量、工程规范与设计决策，全部集中在这里。
 
 #links
 :::u-button

code/g3soft-libs/docs/nuxt.config.ts

@@ -15,7 +15,14 @@ export default defineNuxtConfig({
   // sitemap.xml、llms.txt、OG image 都依赖站点 URL，缺了会导致预渲染 500
   site: {
     url: process.env.DOCS_SITE_URL || 'https://ui.g3soft.dev',
-    name: 'G3Soft UI',
+    name: 'G3Soft 技术文档',
+  },
+
+  // 监听所有网卡：控制台会打印可用的 Local(http://localhost:PORT) 与 Network(局域网地址)。
+  // 这里必须用空串而不是 '0.0.0.0'：listhen 把空串当“全部网卡”，且生成 URL 时回退成 localhost；
+  // 而 '0.0.0.0' 会把 Local 那行显示成 http://0.0.0.0:PORT（浏览器打不开）。
+  devServer: {
+    host: '',
   },
 
   vite: {

code/g3soft-libs/docs/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "nuxt dev",
+    "dev": "node scripts/dev.mjs",
     "build": "nuxt build",
     "generate": "nuxt generate",
     "preview": "nuxt preview"

code/g3soft-libs/docs/scripts/dev.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * 启动文档站 dev server，启动前挑一个真正空闲的端口。
+ *
+ * 为什么不用 Nuxt 自带的端口回退：Nuxt 靠“试绑 host”判断端口是否空闲，而 Windows 上 Node
+ * 默认开启 SO_REUSEADDR，**允许多个进程绑定同一个 addr:port**，于是“能不能绑上”根本判断不出
+ * 冲突 —— 3000 已被别的服务占用时，探测仍然成功，Nuxt 就继续用 3000。
+ *
+ * 因此这里改用“实际建立 TCP 连接”来判断：只要 127.0.0.1 或 ::1 任一能连上，就说明该端口
+ * 正在被监听（可覆盖占用方绑在 0.0.0.0 / 127.0.0.1 / ::1 的所有常见情况），然后依次向上找。
+ *
+ * 起始端口：DOCS_PORT > PORT > 3000。
+ */
+import { spawn } from 'node:child_process'
+import { connect } from 'node:net'
+
+const start = Number(process.env.DOCS_PORT || process.env.PORT || 3000)
+const MAX_TRIES = 100
+
+/** 能否连接到 host:port（能连上即为“正在被监听”） */
+function reachable(port, host) {
+  return new Promise((resolve) => {
+    const socket = connect({ port, host })
+    const done = (busy) => {
+      socket.destroy()
+      resolve(busy)
+    }
+    socket.setTimeout(400)
+    socket.once('connect', () => done(true))
+    socket.once('timeout', () => done(false))
+    socket.once('error', () => done(false))
+  })
+}
+
+async function isBusy(port) {
+  const [v4, v6] = await Promise.all([reachable(port, '127.0.0.1'), reachable(port, '::1')])
+  return v4 || v6
+}
+
+let port = start
+while (port < start + MAX_TRIES && (await isBusy(port))) port++
+
+if (port !== start) console.log(`端口 ${start} 已被占用，改用 ${port}`)
+
+const child = spawn('nuxt', ['dev', '--port', String(port)], {
+  stdio: 'inherit',
+  shell: true,
+})
+child.on('exit', (code) => process.exit(code ?? 0))