Guava Docs

Appearance

文档站常见问题 ​

这里汇总了 Guava UI 文档站从零到上线过程中最常碰到的问题，可直接找相关场景。

环境准备相关 ​

Q: 需要装什么版本的开发环境？ ​

环境版本
node.js24.18.0
npm11.16.0
pnpm11.9.0

版本必须一致

为保证项目开发、构建和部署的一致性，请严格按照上方版本安装，否则可能出现依赖问题。

Q: 怎么安装和管理 Node.js 版本？ ​

用 nvm 管理本地 Node.js 版本：

  • Mac：brew install nvm
  • Windows：从 GitHub Releases 下载安装，注意路径不要带中文与空格

验证安装：

bash
nvm -v   # 输出版本号即成功

Q: nvm 常用命令有哪些？ ​

命令说明
nvm install stable安装最新稳定版本的 node.js
nvm install <version>安装指定版本的 node.js
nvm uninstall <version>卸载指定版本的 node.js
nvm use <version>切换到指定版本的 node.js
nvm alias default <version>设置默认版本的 node.js
nvm ls/ nvm list列出所有安装的版本的 node.js
nvm current当前版本的 node.js
nvm unalias <name>取消指定名称的 别名
echo $NVM_DIRnode.js 安装目录

Q: 安装完 nvm 后，怎么装 Node.js 和 pnpm？ ​

bash
# 1. 安装 Node.js 24.18.0
nvm install 24.18.0

# 2. 安装 pnpm 11.9.0
npm install -g pnpm@11.9.0

# 3. 验证
pnpm -v   # 输出版本号即成功
bash
pnpm install
pnpm dev

Q: 编译器有推荐的插件吗? ​

前端编辑器 vscode 或 trae 可安装以下插件配合开发，提高开发效率

项目根目录下新建 .vscode 目录，创建 extensions.json 文件，添加下述内容

json
{
  "recommendations": [
    "michelemelluso.code-beautifier", // 代码美化
    "ms-ceintl.vscode-language-pack-zh-hans", // 中文语言包
    "usernamehw.errorlens", // 错误提示
    "dbaeumer.vscode-eslint", // eslint
    "lokalise.i18n-ally", // i18n 辅助
    "oderwat.indent-rainbow", // 缩进颜色
    "obkoro1.korofileheader", // 注释
    "esbenp.prettier-vscode", // 格式化
    "antfu.unocss", // unocss
    "octref.vetur", // vue 辅助
    "vue.volar", // vue 辅助
    "formulahendry.auto-close-tag", // 自动关闭标签
    "zhubincong.vue-component" // vue 组件提示
  ]
}

一键添加插件 描述

本地开发相关 ​

Q: 怎么启动项目？ ​

bash
pnpm install   # 安装依赖
pnpm dev       # 启动开发服务器

启动后默认访问地址会被自动复制到剪贴板，打开浏览器粘贴即可。

默认访问地址：http://localhost:4000/默认访问地址会被复制到剪贴板。

Q: 怎么修改开发时的端口号？ ​

编辑 .env.[dev|prod]：

typescript
VITE_PORT: 4000; // 改成你想要的端口

Q: 怎么配置后端接口地址，方便本地调试？ ​

编辑 src/api/server.ts：

typescript
const prefix = '/api';

export default {
  // 本地调试用：直接指向本地后台服务
  gateway_admin: 'http://localhost:5172'

  // 上线时用：走统一 API 前缀
  // gateway_admin: `${prefix}/admin`,
};

Q: request 超时时间太短 / 太长，怎么改？ ​

编辑 .env.[dev|prod]：

typescript
VITE_APP_REQUEST_TIMEOUT: 120000; // 默认 120000ms，按需调整

构建与部署相关 ​

Q: 怎么打包生产环境？ ​

bash
pnpm build    # 产物在 /dist 目录
pnpm preview  # 本地预览打包效果

Q: 双击 dist/index.html 打不开，报错了？ ​

这是正常行为。 生成的 dist/index.html 不是给浏览器直接双击打开的，而是需要 HTTP Server 托管。

正确做法：

  • 开发阶段：用 pnpm preview
  • 生产部署：通过 Nginx / Apache / 其他 HTTP Server 托管 dist 目录- 生产部署：通过 Nginx / Apache / 其他 HTTP Server 托管 dist 目录

Q: 部署到服务器时需要注意什么？ ​

站点 base 为 /，部署时需满足：

  1. 将 dist 目录内容放到 Web 服务器的 根路径 / 下
  2. 通过 HTTP/HTTPS 访问，例如 https://example.com/

如果你的站点不在根路径

需要修改 .env 中的 VITE_BASE_PATH 为你实际的路径前缀。 站点 base 为 /，部署时需满足：

  1. 将 dist 目录内容放到 Web 服务器的 / 路径下
  2. 通过 HTTP/HTTPS 访问，例如 https://example.com/

配置相关 ​

Q: 怎么修改站点标题、默认语言、访问路径？ ​

编辑 .env：

typescript
VITE_TITLE: '站点标题'; // 浏览器标签页标题
VITE_LOCALE: 'zh-cn'; // 默认语言
VITE_BASE_PATH: '/'; // URL 访问路径

Q: .env、.env.dev、.env.prod 这三份文件分别改什么？ ​

文件改什么
.env站点全局配置：标题、语言、访问路径
.env.dev开发环境配置：端口号、API 地址、超时时间
.env.prod生产环境配置：同上，但用于生产构建