Appearance
导入项目
已有项目需要继续维护、调试或迭代时，可以在 项目管理 中导入。当前支持从 GitLab 仓库导入，以及从本地上传项目压缩包导入。
导入前应先确认项目来源可信、依赖可用、许可证合规，并梳理项目中可能包含的环境变量、密钥和外部服务配置。
支持的导入方式
| 方式 | 适用场景 | 需要准备的内容 |
|---|---|---|
| GitLab 仓库 | 项目已在 GitLab 托管，需要持续拉取或推送远端代码。 | 仓库地址、目标分支、具备访问权限的 Token。 |
| 本地上传 | 本地已有可归档项目，需要一次性导入后继续开发。 | .zip、.tar 或 .tar.gz 项目压缩包。 |
导入前检查
在开始导入前，建议逐项检查：
- 项目根目录是否包含完整的源代码、依赖说明和必要配置文件。
- 是否清除了不应提交的密钥、令牌、生产环境连接信息和个人数据。
- 依赖版本、构建脚本和启动方式是否可在目标环境中使用。
- 第三方代码、素材和依赖是否符合企业的许可证与安全规范。
如果项目依赖外部数据库、对象存储或其他服务，导入后应在项目环境中重新确认授权与配置，不能直接复用不明来源的生产配置。
从 GitLab 导入
1. 打开导入入口
进入左侧 项目管理，选择 导入项目，再选择从 GitLab 导入的入口。
图 1：在项目管理中打开导入项目入口。
2. 填写仓库信息
在导入窗口中填写以下内容：
- GitLab 仓库地址：完整的仓库 HTTP 或 HTTPS 地址。
- 远程分支：要导入的分支，例如
main。 - 访问 Token：用于读取私有仓库的访问凭证。
- 项目名称：可选；未填写时使用仓库名称。
- 专家模式：需要按专家项目方式运行时开启。
Token 属于敏感信息，只应填写在当前受信任的导入窗口中；不要把 Token 写入项目文件、需求描述、代码注释或截图。
图 2：填写 GitLab 仓库、分支与访问凭证。
3. 执行导入并检查结果
确认仓库地址和分支无误后，点击 导入项目。导入完成后，进入项目查看文件结构、依赖说明和运行配置；首次运行前，先检查启动脚本是否符合当前项目环境。
本地上传项目
1. 准备项目压缩包
本地上传支持 .zip、.tar 和 .tar.gz 格式。压缩包应以项目文件为主，避免包含依赖缓存、构建产物、日志、密钥和无关的大文件。
如果项目有多个服务或模块，建议在导入前写明各模块的用途、启动顺序和依赖关系，便于后续维护。
2. 选择压缩包并导入
在 导入项目 中选择 本地上传，按页面要求选择一个项目压缩包。需要按专家项目方式继续开发时，可开启专家模式，然后点击 导入项目。
图 3：选择本地项目压缩包并设置专家模式。
3. 查看导入进度
上传和创建项目期间，保持页面打开并等待进度完成。导入失败时，先检查压缩包格式、文件完整性、项目大小和页面提示；不要在不确定文件内容的情况下反复上传。
图 4：查看项目上传和创建进度。
导入后验证
导入完成后，不要直接继续大范围修改。建议按以下顺序进行一次基线验证：
| 检查项 | 验证重点 |
|---|---|
| 文件结构 | 核对源代码、配置文件、静态资源和说明文件是否完整。 |
| 依赖与脚本 | 检查依赖声明、构建脚本和启动命令是否符合预期。 |
| 运行配置 | 确认环境变量、外部服务配置和权限不包含不应使用的生产信息。 |
| 首次运行 | 先完成一次构建或运行验证，再开始通过 AI 编程修改项目。 |
| 核心功能 | 选择一个最小功能路径，确认导入后的项目可以正常打开和操作。 |
如果首次运行失败，先记录错误信息、执行命令和失败步骤，再在项目内说明问题。不要通过删除配置、跳过校验或直接替换未知依赖来掩盖导入问题。
注意事项
- 私有仓库导入前，确认 Token 只具备完成导入所需的最小权限。
- 不要将密钥、令牌、生产环境配置或用户数据打包进项目压缩包。
- 导入第三方项目时，先核查许可证、依赖来源和可执行脚本。
- 导入后如需连接 GitLab 或其他外部服务，应确认当前项目、企业权限与访问范围。
- 页面实际提供的字段和操作以当前版本界面为准；遇到不支持的项目格式，应先整理项目结构再导入。