本文详解如何通过单仓库多子目录结构与 netlify.toml 重定向配置，在同一 Netlify 域名（如 example.netlify.app）下托管主应用及多个子路径 React 应用（如 /app-one、/app-two），支持共用仓库、独立构建、统一访问。
本文详解如何通过单仓库多子目录结构与 `netlify.toml` 重定向配置，在同一 netlify 域名（如 `example.netlify.app`）下托管主应用及多个子路径 react 应用（如 `/app-one`、`/app-two`），支持共用仓库、独立构建、统一访问。
要在 Netlify 上实现 一个域名承载多个独立 React 应用（例如 https://example.netlify.app 为主站，/app-one 和 /app-two 为子应用），关键在于统一部署入口 + 路由代理 + 静态文件隔离。推荐采用 单仓库多目录结构 + 自定义 netlify.toml 重定向规则 的方案，无需多个 Netlify 站点，避免跨域与管理碎片化。
✅ 推荐架构：单仓库、多子目录、单部署站点
将所有应用组织在同一 Git 仓库根目录下，结构清晰、版本可控：
root/ ├── app-one/ # React 应用一（含 package.json、src/、public/ 等） ├── app-two/ # React 应用二 ├── main-app/ # 主 React 应用 ├── netlify.toml # 全局部署与重定向配置 └── package.json # （可选）根目录聚合脚本，如 "build:all": "npm run build --prefix main-app && npm run build --prefix app-one && npm run build --prefix app-two"
⚠️ 注意：每个子应用需确保其
package.json中的"homepage"字段正确设置（如"/app-one"），否则路由跳转和静态资源路径会失效。例如app-one/package.json应包含："homepage": "/app-one"
?️ 配置 netlify.toml 实现路径级分发
在仓库根目录创建 netlify.toml，定义构建指令与路径重定向规则：
# netlify.toml [build] command = "npm run build:all" # 或依次构建各应用（见下方说明） publish = "main-app/build" # 主应用构建产物作为默认发布目录（必须存在） # 将 /app-one/* 请求全部指向 app-one 的 index.html（支持客户端路由） [[redirects]] from = "/app-one/*" to = "/app-one/index.html" status = 200 # 同理处理 app-two [[redirects]] from = "/app-two/*" to = "/app-two/index.html" status = 200 # 所有其他路径（包括 /）默认指向主应用 [[redirects]] from = "/*" to = "/main-app/index.html" status = 200
? 原理说明：Netlify 的重定向规则在服务器端生效，当用户访问
/app-one/dashboard时，Netlify 不返回 404，而是将请求“内部重写”为/app-one/index.html，交由app-one的 React Router 处理前端路由——这正是 Create React App 等 SPA 框架所需的history模式支持。
? 构建产物部署：静态文件需共存于同一输出目录
由于 Netlify 只允许指定一个 publish 目录，你需要将各应用的 build/ 输出合并到该目录下对应子路径中。推荐两种方式：
方式一：使用构建脚本自动复制（推荐）
在根目录 package.json 中添加构建脚本：
{
"scripts": {
"build:main": "cd main-app && npm run build",
"build:app-one": "cd app-one && npm run build",
"build:app-two": "cd app-two && npm run build",
"postbuild:app-one": "mkdir -p main-app/build/app-one && cp -r app-one/build/* main-app/build/app-one/",
"postbuild:app-two": "mkdir -p main-app/build/app-two && cp -r app-two/build/* main-app/build/app-two/",
"build:all": "npm run build:main && npm run build:app-one && npm run build:app-two"
}
}
✅ 最终 main-app/build/ 目录结构如下：
main-app/build/
├── index.html # 主应用入口
├── static/ # 主应用资源
├── app-one/
│ ├── index.html # app-one 入口（已适配 homepage="/app-one"）
│ └── static/ # app-one 资源
└── app-two/
├── index.html # app-two 入口
└── static/
方式二：使用 netlify-plugin-subdirectories 插件（进阶）
安装官方插件自动完成子目录构建与发布，适合大型项目，详见 Netlify 插件文档。
✅ 部署与验证
- 将该仓库推送到 GitHub/GitLab；
- 在 Netlify 控制台新建站点，选择该仓库；
- 构建设置中确认：
-
Build command:
npm run build:all -
Publish directory:
main-app/build
-
Build command:
- 保存并触发部署；
- 部署成功后访问：
-
https://example.netlify.app→ 主应用 -
https://example.netlify.app/app-one→ app-one -
https://example.netlify.app/app-two→ app-two
-
⚠️ 注意事项与最佳实践
-
React Router 配置：每个子应用必须使用
<browserrouter basename="/app-one"></browserrouter>（或通过homepage+HashRouter降级），否则导航将跳转至根路径； -
静态资源路径：确保
public/中的图片、manifest 等引用路径与homepage一致（如<link rel="manifest" href="%PUBLIC_URL%/manifest.json">会自动解析为/app-one/manifest.json）； -
环境变量隔离：
.env文件不跨应用共享，各子应用应维护自己的.env.production； -
CI/CD 效率：可配置 Netlify Build Plugins 或条件构建，避免每次修改
app-one都重建全部应用； -
替代方案对比：若应用完全解耦、团队独立，也可用 Netlify Split Testing 或子域名（
app-one.example.netlify.app），但路径模式更利于 SEO 统一与品牌一致性。
通过以上配置，你将以最小运维成本，在单一 Netlify 域名下优雅承载多个 React SPA，兼顾开发独立性与线上统一性。
