advich-content-frontend/docs/LOCAL_TEST_GUIDE.md

本地测试指南 - localStorage 共享

问题

本地开发时，React 项目和 JeecgBoot 运行在不同端口：

• React: http://localhost:3000
• JeecgBoot: http://localhost:3100

不同端口 = 不同域名 = localStorage 不共享

解决方案

方案 1：Nginx 本地代理（推荐）✅

通过 Nginx 将两个项目统一到一个端口。

步骤 1：安装 Nginx

macOS:

brew install nginx

Windows: 下载并安装：https://nginx.org/en/download.html

Linux:

sudo apt-get install nginx

步骤 2：配置 Nginx

使用项目根目录的 nginx.local.conf 文件：

# macOS/Linux
sudo cp nginx.local.conf /usr/local/etc/nginx/servers/local-dev.conf

# 或者直接编辑 nginx.conf
sudo nano /usr/local/etc/nginx/nginx.conf

步骤 3：启动服务

# 1. 启动 React 项目（端口 3000）
npm run dev

# 2. 启动 JeecgBoot 前端（端口 3100）
cd /path/to/jeecg-boot-frontend
npm run serve

# 3. 启动 Nginx
sudo nginx
# 或重启
sudo nginx -s reload

步骤 4：访问

现在所有服务都通过 http://localhost:8080 访问：

• React 项目：http://localhost:8080/spaces/
• JeecgBoot：http://localhost:8080/system/user

✅ localStorage 自动共享！

停止 Nginx

sudo nginx -s stop

---

方案 2：修改 hosts + 反向代理

使用自定义域名 + Nginx。

步骤 1：修改 hosts

sudo nano /etc/hosts

添加：

127.0.0.1 local-dev.com

步骤 2：配置 Nginx

server {
    listen 80;
    server_name local-dev.com;

    location /spaces/ {
        proxy_pass http://localhost:3000/spaces/;
    }

    location / {
        proxy_pass http://localhost:3100/;
    }
}

步骤 3：访问

• React: http://local-dev.com/spaces/
• JeecgBoot: http://local-dev.com/system/user

---

方案 3：URL 参数传递（临时方案）

仅用于快速测试，不推荐长期使用。

React 端

跳转时通过 URL 参数传递 token（已在 jeecgNavigation.ts 中实现）：

// 开发环境自动添加 token 参数
navigateToJeecg('/system/user');
// 实际跳转：http://localhost:3100/system/user?_dev_token=xxx

JeecgBoot 端

需要在 JeecgBoot 中添加代码读取 URL 参数并写入 localStorage：

// JeecgBoot: src/main.js 或 App.vue
if (process.env.NODE_ENV === 'development') {
  const urlParams = new URLSearchParams(window.location.search);
  const devToken = urlParams.get('_dev_token');
  
  if (devToken) {
    try {
      localStorage.setItem(
        '内容中心管理系统__PRODUCTION__1.0.0__COMMON__LOCAL__KEY__',
        devToken
      );
      console.log('[Dev] Token synced from URL parameter');
      
      // 移除 URL 参数
      window.history.replaceState({}, '', window.location.pathname);
    } catch (e) {
      console.error('[Dev] Failed to sync token:', e);
    }
  }
}

---

方案 4：浏览器插件同步

使用浏览器插件在不同端口间同步 localStorage。

Chrome 插件：Storage Area Explorer

1. 安装插件
2. 手动复制 localStorage 数据
3. 在另一个端口粘贴

缺点： 手动操作，不方便

---

推荐方案对比

方案	优点	缺点	推荐度
Nginx 代理	完全模拟生产环境，自动共享	需要安装 Nginx	⭐⭐⭐⭐⭐
hosts + Nginx	使用自定义域名，更真实	配置稍复杂	⭐⭐⭐⭐
URL 参数	快速测试，无需额外配置	需要修改 JeecgBoot 代码	⭐⭐⭐
浏览器插件	无需代码修改	手动操作，不方便	⭐⭐

最佳实践

开发环境

使用 Nginx 本地代理：

http://localhost:8080/spaces/     → React
http://localhost:8080/system/user → JeecgBoot

测试环境

使用 自定义域名：

http://test.your-domain.com/spaces/     → React
http://test.your-domain.com/system/user → JeecgBoot

生产环境

使用 同一域名：

https://your-domain.com/spaces/     → React
https://your-domain.com/system/user → JeecgBoot

快速开始（Nginx 方案）

# 1. 安装 Nginx
brew install nginx  # macOS
# 或
sudo apt-get install nginx  # Linux

# 2. 复制配置文件
sudo cp nginx.local.conf /usr/local/etc/nginx/servers/local-dev.conf

# 3. 启动 React（端口 3000）
npm run dev

# 4. 启动 JeecgBoot（端口 3100）
cd /path/to/jeecg-boot-frontend
npm run serve

# 5. 启动 Nginx
sudo nginx

# 6. 访问测试
open http://localhost:8080/spaces/

验证 localStorage 共享

步骤 1：在 React 项目登录

访问：http://localhost:8080/spaces/login

步骤 2：检查 localStorage

打开浏览器控制台：

localStorage.getItem('内容中心管理系统__PRODUCTION__1.0.0__COMMON__LOCAL__KEY__')

应该能看到 token 数据。

步骤 3：跳转到 JeecgBoot

点击跳转按钮，或直接访问：

http://localhost:8080/system/user

步骤 4：验证免登录

如果 JeecgBoot 页面直接显示内容（没有跳转到登录页），说明 localStorage 共享成功！✅

故障排查

问题 1：Nginx 启动失败

# 检查配置文件语法
sudo nginx -t

# 查看错误日志
tail -f /usr/local/var/log/nginx/error.log

问题 2：端口被占用

# 查看端口占用
lsof -i :8080

# 杀死进程
kill -9 <PID>

问题 3：代理不生效

检查 Nginx 配置中的端口是否正确：

proxy_pass http://localhost:3000/;  # React 端口
proxy_pass http://localhost:3100/;  # JeecgBoot 端口

问题 4：localStorage 还是不共享

1. 确认访问的是 http://localhost:8080（不是 3000 或 3100）
2. 清除浏览器缓存
3. 检查 Nginx 日志

总结

本地测试 localStorage 共享的关键：

1. ✅ 使用同一个端口（通过 Nginx 代理）
2. ✅ 使用同一个域名（localhost）
3. ✅ 使用同一个协议（http）

只要满足这三点，localStorage 就会自动共享！