如何在虚拟主机上部署Qwik JS？自定义服务器部署问题求助

前置准备 #

• 本地执行npm run build完成项目构建，生成dist目录（不同Qwik模板的构建产物路径可能不同，比如部分模板会把静态文件放在dist/client下，以你项目实际结构为准）
• 确认虚拟主机支持的运行环境：仅静态文件托管，还是支持Node.js？大部分虚拟主机至少支持静态文件，部分提供Node.js运行环境。

1. 纯静态部署（适合无SSR/API需求的Qwik项目） #

• 将构建生成的静态文件目录（比如dist/client）里的所有文件，上传到虚拟主机的网站根目录（通常是public_html、www这类目录）
• 若项目使用了Qwik City路由，必须配置URL重写规则，否则刷新页面会出现404错误：
  • Apache服务器：在网站根目录创建.htaccess文件，写入以下内容：

    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
    

  • Nginx服务器：在站点配置中添加如下规则：

    location / {
        try_files $uri $uri/ /index.html;
    }
    

• 上传完成后直接访问你的域名即可。

2. Node.js服务器部署（适用于需要SSR/API的Qwik项目） #

• 先确认虚拟主机支持Node.js，且版本满足Qwik要求（建议Node.js 16.x及以上）
• 上传项目文件（排除node_modules目录）到虚拟主机的项目目录（比如~/my-qwik-app）
• 在虚拟主机终端执行npm install --production安装生产依赖
• 确保package.json中有正确的启动脚本，示例：

  "scripts": {
    "start": "node dist/server/entry.server.js"
  }
  

  （脚本路径需根据你的项目构建后的实际路径调整）
• 用pm2管理进程，避免服务器重启后服务终止：
  • 安装pm2：npm install -g pm2
  • 启动项目：pm2 start npm --name "qwik-app" -- start
  • 保存pm2配置并设置开机自启：pm2 save && pm2 startup
• 配置反向代理，将域名请求转发到Node.js服务的端口（默认3000）：
  • Nginx示例：

    server {
        listen 80;
        server_name your-domain.com;
    
        location / {
            proxy_pass http://localhost:3000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }
    }
    

  • Apache示例（需先启用mod_proxy和mod_proxy_http模块）：

    ProxyRequests Off
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
    

常见问题排查 #

• 404错误：检查静态文件是否上传到正确目录，路由重写规则是否配置生效
• 服务启动失败：核对Node.js版本是否符合要求，生产依赖是否安装完整，端口是否被占用
• 资源加载失败：若项目部署在子目录，需在vite.config.js中设置base: '/your-subfolder/'，确保资源路径正确

内容的提问来源于stack exchange，提问作者Robbani Bd