DocumentaçãoKCS da Experience Cloud

Resolução de variáveis de ambiente do Dispatcher que não são resolvidas ou aplicadas no AEM Dispatcher

Última atualização: 27 de junho de 2026

As variáveis de ambiente do Dispatcher não são resolvidas, ficam indisponíveis dentro de IfDefine blocos ou se comportam de forma inconsistente entre ambientes quando têm escopo e nome incorretos, são atribuídas ao serviço errado, são referenciadas em diretivas sem suporte ou são substituídas por uma configuração inválida do dispatcher. Somente no AEMaaCS ENVIRONMENT_DEV, ENVIRONMENT_STAGE e ENVIRONMENT_PROD são inseridos conforme definido pelo Apache, enquanto as variáveis personalizadas do Cloud Manager funcionam apenas para substituição de cadeia de caracteres e não podem ser usadas dentro de IfDefine; no AMS, as variáveis devem ser definidas em /etc/sysconfig/httpd. Validar a definição da variável, confirmar que ela é usada em um contexto compatível e verificar as cargas corretas do vhost no tempo de execução restaura os valores esperados.

Descrição description

Ambientes:

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • AEM Managed Services (AMS)
  • AEM Dispatcher (Apache) em níveis de publicação
  • Dispatcher SDK para validação local

Problema/sintomas:

  • Um cabeçalho personalizado gera o nome da variável literal em vez do valor resolvido, como Access-Control-Allow-Origin: ${VAR_NAME}.
  • O validador do Dispatcher relata AH00111: a variável de configuração ${VAR_NAME} não está definida.
  • O Apache relata Autoridade inválida para uma variável vazia usada em um host virtual.
  • Falha ao aplicar IfDefine blocos porque ENVIRONMENT_STAGE ou ENVIRONMENT_DEV não foi detectado.
  • O pipeline falha durante a validação ou implantação do dispatcher sem um erro claro e o validador local mostra variáveis indefinidas.
  • As regras específicas do ambiente nunca são executadas porque o RDE não tem ENVIRONMENT_RDE definido.

Causa raiz:

A resolução da variável Dispatcher varia de acordo com a plataforma e o tipo de diretiva. No AEMaaCS, somente ENVIRONMENT_DEV, ENVIRONMENT_STAGE e ENVIRONMENT_PROD são definidos pelo Apache; as variáveis do Cloud Manager estão disponíveis somente como substituições de sequência e não podem ser usadas em IfDefine. O uso de variáveis dentro de diretivas sem suporte (IfDefine, <If> ou um ServerName vazio ou não defini-las para o pipeline e para o tempo de execução produz valores indefinidos. Quando os links simbólicos do vhost ou os mapeamentos do host virtual do farm estão incorretos, o arquivo vhost errado é carregado e as variáveis parecem não funcionais. Cadeias vazias em um vhost ServerName ou ServerAlias causam falhas de tempo de execução do Apache. O AMS requer variáveis definidas em /etc/sysconfig/httpd, e valores incompatíveis entre ambientes causam comportamento incorreto.

Como confirmar

  1. Confirme se a variável existe e se está definida corretamente. No Cloud Manager, vá para Programa > Ambiente > Variáveis de ambiente e confirme se o nome (diferencia maiúsculas de minúsculas) e o valor da variável correspondem exatamente às referências das configurações do Dispatcher. Confirme se a variável está definida para o serviço de Publicação, já que o dispatcher não está presente nos níveis do Autor.
  2. Confirme se o tipo de variável é compatível no contexto em que é usado. O AEMaaCS não é compatível com as variáveis de ambiente do Cloud Manager dentro do IfDefine — somente ENVIRONMENT_DEV, ENVIRONMENT_STAGE e ENVIRONMENT_PROD funcionam lá. Se você vir IfDefine encapsulando uma variável Cloud Manager, esse uso não é suportado.
  3. Confirme se nenhuma variável resolve para uma string vazia, especialmente em vhosts. Uma variável FQDN vazia em um ServerName produz o erro Apache Autoridade Inválida.

Resolução resolution

  1. Corrija a definição de variável ou atribuição de serviço. Se o nome ou valor estiver errado, ou se for atribuído ao serviço errado, adicione ou corrija a variável de ambiente no Cloud Manager e execute o pipeline novamente.
  2. Use variáveis somente em contextos compatíveis. Mantenha as variáveis do Cloud Manager em substituição de string, cabeçalhos, regras de regravação e configuração do vhost. Para a lógica específica do ambiente, use uma expressão Apache como <If "${ENV:ENVIRONMENT_TYPE} == 'dev'"> ou a definição ENVIRONMENT_DEV em vez de vincular uma variável personalizada em IfDefine.
  3. Definir variáveis referenciadas em custom.vars. Adicione uma entrada Define para cada variável referenciada nos arquivos vhost, no formato Define VAR_NAME ${varname}. Com as definições em vigor, o validador para de relatar AH00111: a variável de configuração não está definida.
  4. Verifique se os symlinks do vhost e do farm são válidos. Execute o validador do dispatcher localmente; os erros aparecem quando enabled_vhosts ou enabled_farms contêm arquivos regulares em vez de symlinks. Recrie as ligações simbólicas com ln -s em src/conf.d/enabled_vhosts e enabled_farms até que o validador mostre zero erros.
  5. Verifique se o vhost correto é carregado no tempo de execução. Confirme se os arquivos do farm apontam para o arquivo virtualhosts.any correto — um mapeamento /virtualhosts incorreto faz com que o Dispatcher carregue o vhost padrão e ignore as variáveis personalizadas. Corrija o bloco /virtualhosts do farm para incluir ../virtualhosts/virtualhosts.any, visite uma página e confirme se o cabeçalho personalizado mostra o valor resolvido.
  6. Somente para AMS, defina variáveis em /etc/sysconfig/httpd. Conecte o SSH ao servidor do Dispatcher e execute cat /etc/sysconfig/httpd para confirmar se as variáveis refletem o ambiente correto. Em seguida, reinicie o Apache com sudo systemctl restart httpd. Se os valores forem revertidos, entre em contato com o Suporte do AMS.
  7. Teste localmente usando a SDK do Dispatcher. Execute o dispatcher localmente com as Ferramentas do AEM SDK Dispatcher e, em seguida, confirme a resolução do cabeçalho com curl -I http://localhost:8080/....

Validação

  1. Execute dispatcher-sdk/bin/validate src e confirme se não foram exibidos erros de variável indefinida (AH00111).
  2. Verifique os cabeçalhos de resposta HTTP reais com curl -I ou DevTools do navegador e confirme se as variáveis resolvem para seus valores de Cloud Manager.

Leitura relacionada

recommendation-more-help
experience-cloud-kcs-help-kbarticles