Appearance
ZXManage 项目配置功能使用文档
一、功能概述
项目配置模块用于管理项目的基础信息、本地服务、打包命令及服务器上传等核心配置，支持对已有项目进行参数修改与功能扩展，是项目管理与本地服务的核心入口。 
图1：项目配置界面
图2：项目配置界面
二、基础信息配置
1. 配置项说明
| 配置项 | 说明 | 操作要求 |
|---|---|---|
| 项目名称 | 项目在 ZXManage 中的显示名称 | 可修改，支持中英文 |
| 所需功能 | 已启用的功能模块 | 可勾选/取消：文件管理、代码管理、笔记、项目打包 |
| 文件夹名称 | 项目在本地的代码目录名称 | 建议使用英文，避免路径解析异常 |
| GIT地址 | 项目关联的远程 Git 仓库地址 | 支持 Gitee/GitHub 等平台，用于代码同步 |
| ICON | 项目展示图标 | 可上传自定义图片，支持替换/删除 |
2. 操作步骤
①. 修改需要调整的配置项（如项目名称、GIT地址等）。
②. 点击「保存」按钮，完成配置更新。
💡 Tips：
- 文件夹名称修改后，会同步更新本地项目目录名称，请谨慎操作。
- 若项目已关联 Git，修改 GIT 地址后需重新拉取/推送代码以生效。
三、本地服务配置
1. 功能说明
本地服务采用 Nginx 启动，目前仅支持 前端（VUE、REACT） 及 NODE 类型项目，用于快速预览项目运行效果，并可配置代理转发后端接口。
2. 配置项说明
点击「添加配置」后，会弹出添加本地服务配置弹窗，各字段含义如下：
| 配置项 | 必填 | 说明 | 输入要求 |
|---|---|---|---|
| 名称 | ✅ | 服务的唯一标识 | 建议使用英文，避免启动报错 |
| 备注 | ❌ | 服务用途说明 | 用于区分不同环境或场景，如“开发环境预览” |
| 前端基础路径 | ✅ | 前端项目的访问根路径 | 默认值为 /，若项目部署在子路径（如 /demo/）需修改 |
| 端口 | ✅ | 本地服务监听的端口号 | 需为未被占用的端口（如 8080、3000） |
| 打包环境 | ✅ | 选择对应的打包环境 | 关联已配置的打包命令，用于指定打包产物目录 |
| 后端服务地址 | ❌ | 接口代理配置 | 可配置多个，包含「服务前缀」和「服务地址」 |
图3：本地服务配置项
3. 操作步骤
①. 填写基础信息 - 输入名称（英文）和备注。 - 设置前端基础路径（默认 /）和端口号。 - 从下拉菜单选择打包环境。
②. 配置后端代理（可选） - 点击「+ 添加服务地址」。 - 填写「服务前缀」（如 /api）和「服务地址」（如 http://localhost:3000）。 - 如需多个代理规则，可继续点击「添加服务地址」新增。 - 点击右侧 - 按钮可删除已配置的代理项。
③. 保存配置 - 确认所有信息无误后，点击「确定」完成配置。 - 配置将显示在本地服务列表中，可后续编辑、删除、预览修改生成的nginx配置文件。
4. 关键配置示例
示例 1：基础前端服务
yaml
名称: dev-preview
备注: 开发环境预览
前端基础路径: /
端口: 8080
打包环境: 生产
后端服务地址: 无示例 2：带接口代理的生产预览服务
yaml
名称: prod-preview
备注: 生产环境模拟预览
前端基础路径: /
端口: 8081
打包环境: 测试
后端服务地址:
- 服务前缀: /api
服务地址: http://api.example.com
- 服务前缀: /upload
服务地址: http://upload.example.com5. 注意事项与 Tips
💡 Tips：
- 端口冲突：若端口被占用，服务将启动失败，请更换未使用的端口。
- 基础路径：若前端项目构建时配置了
base（如 Vite 的base选项），此处需保持一致。- 代理规则：Nginx 会将匹配「服务前缀」的请求转发到对应的「服务地址」，实现前后端分离开发。
⚠️ 警告：
- 名称必须使用英文，否则可能导致 Nginx 配置文件生成失败。
- 打包环境需提前在「打包命令配置」中定义，否则无法选择。
- 启动服务前，请确保项目已完成对应环境的打包。
6. 服务管理
配置完成后，可在「本地服务配置」列表中对服务进行管理：
- 编辑：修改服务配置参数。
- 删除：移除不再需要的服务配置。
- 预览修改生成的nginx配置文件:配置更高级专业以及自定义的nginx配置。
- 启动/停止：控制服务运行状态（在「主页」模块操作）。
四、打包命令配置
1. 功能说明
用于配置项目打包与本地服务启动的执行命令，支持自定义脚本以适配不同项目结构。
2. 特殊场景配置
若代码根目录并非执行命令的目录（如 monorepo 结构），需使用 --prefix 指定目标目录：
bash
# 示例：在根目录执行子目录的打包命令
npm --prefix ./packages/demo run build3. 操作步骤
- 点击「+ 添加打包命令」，输入命令名称与具体脚本。
- 点击「保存」，完成命令配置。
- 后续在「项目打包」和「本地服务」模块可直接调用已配置的命令。
📌 提示：
- 命令需与项目
package.json中定义的脚本一致。- 支持配置多条打包命令，适配不同环境（开发/生产）。
五、服务器上传配置
1. 功能说明
该模块用于配置项目打包产物上传至远程服务器的规则，支持 FTP/SFTP/SSH 三种连接协议，可自定义上传路径、目录命名规则，将打包后的产物直接提交至远程服务器，无需额外连接 FTP/SFTP 工具，实现真正的“打包即发布”。
2. 新增/编辑配置项说明
点击「添加配置」后，弹出服务器上传配置弹窗，各字段详细说明如下：
| 配置项 | 必填 | 说明 | 输入要求/示例 |
|---|---|---|---|
| 名称 | ✅ | 配置唯一标识，用于界面区分显示 | 如：生产环境部署、测试服务器 |
| 连接类型 | ✅ | 选择服务器连接协议 | 可选： ✅ FTP（常规文件传输） ✅ SFTP（安全FTP，推荐） ✅ SSH（远程命令执行/文件传输） |
| 服务器地址 | ✅ | 目标服务器域名或IP | 如：192.168.1.100、ftp.example.com |
| 端口 | ✅ | 服务器服务端口 | 协议默认端口： • FTP： 21• SFTP： 22• SSH： 22 |
| 用户名 | ✅ | 服务器登录账号 | 如：root、ftpuser |
| 密码 | ✅ | 服务器登录密码 | 输入对应账号的登录密码；支持右侧眼睛图标切换显示 |
| 作者名称 | ❌ | 上传文件/目录的作者标识 | 配合目录名变量使用 |
| 文件路径 | ✅ | 上传文件的目标根路径 | 服务器上存放文件的绝对路径，如：/var/www/html、/home/user/deploy |
| 目录名 | ❌ | 自定义上传子目录规则 | 核心配置，支持固定名称或变量动态生成，详细规则见下方说明 |
图4：服务器上传配置项
3. 核心配置：目录名（关键）
🔹 规则说明
目录名 为选填，用于在 文件路径 根路径下创建子目录，实现分类管理。
- 为空时：上传的文件/产物直接存放至
文件路径配置的根路径下。 - 非空时：自动在根路径下创建以该配置命名的子目录，文件上传至该子目录。
🔹 变量语法（支持动态生成目录）
可通过内置变量实现目录名动态生成，变量格式为 $变量名，部分变量支持自定义格式，示例如下：
| 内置变量 | 含义 | 用法示例 | 生成结果示例 |
|---|---|---|---|
$projectName | 当前项目名称 | 项目_$projectName | 项目_demo-test |
$author | 配置的「作者名称」 | 作者_$author | 作者_dev-team |
$remark | 自定义备注（需配合脚本/界面输入） | 备注_$remark | 备注_正式部署 |
$time(格式) | 上传时间（支持自定义格式） | $time(YYYY-MM-DD) $time(yyyyMMddHHmm) | 2026-03-23 202603231540 |
🔹 目录名配置示例
| 目录名配置 | 实际效果 | 说明 |
|---|---|---|
| （留空） | 直接上传至 /var/www/html | 根路径直接部署 |
dist | 上传至 /var/www/html/dist | 固定子目录 |
$projectName-$time(YYYYMMDD) | 上传至 /var/www/html/demo-20260323 | 项目名+日期动态目录 |
$author/$time(yyyy-MM) | 上传至 /var/www/html/dev-team/2026-03 | 作者+年月分级目录 |
4. 操作步骤
- 填写基础连接信息
- 选择 连接类型（优先推荐 SFTP/SSH，安全性更高）。
- 输入 服务器地址、端口、用户名、密码。
- 配置上传路径
- 填写 文件路径（服务器目标根目录）。
- 按需填写 目录名（支持固定名称或变量，参考上述规则）。
- 补充作者信息
- 填写 作者名称，用于配合目录变量使用。
- 保存配置
- 确认所有信息无误后，点击「确定」，配置将保存至列表。
5. 最佳实践与注意事项
💡 Tips：
- 协议选择：生产环境优先选 SFTP/SSH，避免 FTP 明文传输带来的安全风险。
- 目录变量：推荐使用
$projectName+$time组合，实现按项目+日期归档，避免文件覆盖。- 路径权限：确保配置的
文件路径对登录账号有写权限，否则上传会失败。- 密码安全：建议使用密钥登录（SSH/SFTP），若仅支持密码登录，需定期更换密码并做好保密。
⚠️ 警告：
- 目录名变量需严格遵循语法（如
$time(格式)括号内格式不能写错），否则会导致目录生成失败。- 上传前需提前确认
文件路径存在且可写，避免因目录不存在导致上传失败。
6. 配置管理
已保存的服务器上传配置可在列表中进行：
- 编辑：修改上传路径、连接信息等参数。
- 删除：移除不再使用的部署配置。
- 一键上传：在「项目打包」模块选择对应配置，直接执行上传流程。
六、常见问题与 Tips
💡 Tips：
- 所有配置修改后必须点击「保存」才能生效。
- 本地服务启动失败时，可检查 Nginx 状态与打包产物目录是否存在。
- 服务器上传配置需提前配置 SSH 免密登录，避免手动输入密码。
⚠️ 警告：
- 修改文件夹名称或 GIT 地址可能导致项目文件丢失或代码不同步，请先备份重要数据。
- 打包命令配置错误会导致项目打包失败，请仔细核对脚本语法。