From 5dba6ac5b4366f34334951827587a91e0957c9a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A5=80=E6=A2=A6?= <3501646051@qq.com> Date: Wed, 22 Oct 2025 16:26:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E6=8C=87=E5=8D=97=E5=B9=B6=E5=A2=9E=E5=BC=BA=E5=90=AF=E5=8A=A8?= =?UTF-8?q?=E8=84=9A=E6=9C=AC=E5=8A=9F=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 扩展 README.md 中的安装说明，增加环境要求、详细步骤和常见问题排查 - 重写 start.bat 脚本，支持参数化配置并添加多重回退机制 - 优化开发服务器启动流程，提升不同环境下的兼容性 --- README.md | 40 +++++++++++++++++++++++++++++++++---- start.bat | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 95 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ba95820..90304b1 100644 --- a/README.md +++ b/README.md @@ -22,11 +22,43 @@ ## 安装 -确保您的 Node.js 版本符合要求（^20.6.0 || >=22.0.0），然后执行以下命令： +- 环境要求： + - Node.js：`^20.6.0` 或 `>=22.0.0`（推荐使用当前 LTS 或稳定版） + - npm：`>=10` -```sh -npm i -``` +- 安装步骤： + 1. 在项目根目录执行依赖安装： + ```sh + npm install + ``` + 2. 启动开发服务器（任选其一）： + - 常规方式： + ```sh + npm run docs:dev + ``` + - Windows 快捷方式（尝试监听 `0.0.0.0` 以便局域网访问）： + ```bat + .\start.bat + ``` + - 若端口或权限受限，使用备用命令（绑定到本机并更换端口）： + ```sh + npx vuepress@2.0.0-rc.24 dev docs --port 5173 --host localhost + ``` + 3. 打开浏览器访问： + - `http://localhost:4567/`（默认）或 + - `http://localhost:5173/`（如果使用备用命令） + +- 常见问题与排查： + - “`vuepress` 不是内部或外部命令”：通常为依赖未安装或安装失败，执行 `npm install` 后重试。 + - “listen EACCES: permission denied 0.0.0.0:4567”：端口或绑定权限受限，改用 `--host localhost` 或更换端口（如 `--port 5173`）。 + - 需要清理缓存后重试： + ```sh + npm run docs:dev-clean + ``` + - 更换端口示例（以 8080 为例）： + ```sh + npx vuepress dev docs --port 8080 --host localhost + ``` ## 使用 diff --git a/start.bat b/start.bat index 7a2e5a8..0502d1a 100644 --- a/start.bat +++ b/start.bat @@ -1 +1,59 @@ -npm run docs:dev -- --host 0.0.0.0 \ No newline at end of file +@echo off +setlocal ENABLEDELAYEDEXPANSION + +REM Usage: +REM start.bat [host] [port] +REM Examples: +REM start.bat -> try 0.0.0.0:4567, fallback to localhost and 5173 +REM start.bat local 8080 -> localhost:8080 +REM start.bat lan 4567 -> 0.0.0.0:4567 + +set HOST=%~1 +if "%HOST%"=="" set HOST=0.0.0.0 +if /I "%HOST%"=="lan" set HOST=0.0.0.0 +if /I "%HOST%"=="local" set HOST=localhost + +set PORT=%~2 +if "%PORT%"=="" set PORT=4567 +set FALLBACK_PORT=5173 + +echo [Start] VuePress dev on host %HOST% port %PORT% +call npx vuepress@2.0.0-rc.24 dev docs --host %HOST% --port %PORT% +if %ERRORLEVEL% EQU 0 goto success + +REM Fallback 1: switch to localhost same port +if NOT "%HOST%"=="localhost" ( + echo [Fallback] switch to localhost on same port %PORT%... + call npx vuepress@2.0.0-rc.24 dev docs --host localhost --port %PORT% + if %ERRORLEVEL% EQU 0 goto success +) + +REM Fallback 2: clean cache and use localhost on fallback port +if NOT "%PORT%"=="%FALLBACK_PORT%" ( + echo [Fallback] clean cache and start on localhost:%FALLBACK_PORT%... + call npx vuepress@2.0.0-rc.24 dev docs --clean-cache --clean-temp --host localhost --port %FALLBACK_PORT% + if %ERRORLEVEL% EQU 0 ( + set HOST=localhost + set PORT=%FALLBACK_PORT% + goto success + ) +) + +REM Fallback 3: try another common port +set ALT_PORT=8080 +if NOT "%PORT%"=="%ALT_PORT%" ( + echo [Fallback] try localhost:%ALT_PORT%... + call npx vuepress@2.0.0-rc.24 dev docs --host localhost --port %ALT_PORT% + if %ERRORLEVEL% EQU 0 ( + set HOST=localhost + set PORT=%ALT_PORT% + goto success + ) +) + +echo [Error] Failed to start dev server. Please check firewall or port usage. +exit /b 1 + +:success +echo [Ready] Open http://localhost:%PORT%/ (or http://%HOST%:%PORT%/ if accessible) +exit /b 0 \ No newline at end of file